chore: limit the exposed property of an export

himanshusinghs · himanshusinghs · commit 92e03995486f · 2025-08-07T19:03:36.000+02:00
diff --git a/src/common/sessionExportsManager.ts b/src/common/sessionExportsManager.ts
@@ -14,13 +14,36 @@ import { LoggerBase, LogId } from "./logger.js";
 export const jsonExportFormat = z.enum(["relaxed", "canonical"]);
 export type JSONExportFormat = z.infer<typeof jsonExportFormat>;
 
-export type Export = {
-    name: string;
-    uri: string;
-    path: string;
-    createdAt: number;
+type StoredExport = {
+    exportName: string;
+    exportURI: string;
+    exportPath: string;
+    exportCreatedAt: number;
 };
 
+/**
+ * Ideally just exportName and exportURI should be made publicly available but
+ * we also make exportPath available because the export tool, also returns the
+ * exportPath in its response when the MCP server is running connected to stdio
+ * transport. The reasoning behind this is that a few clients, Cursor in
+ * particular, as of the date of this writing (7 August 2025) cannot refer to
+ * resource URIs which means they have no means to access the exported resource.
+ * As of this writing, majority of the usage of our MCP server is behind STDIO
+ * transport so we can assume that for most of the usages, if not all, the MCP
+ * server will be running on the same machine as of the MCP client and thus we
+ * can provide the local path to export so that these clients which do not still
+ * support parsing resource URIs, can still work with the exported data. We
+ * expect for clients to catch up and implement referencing resource URIs at
+ * which point it would be safe to remove the `exportPath` from the publicly
+ * exposed properties of an export.
+ *
+ * The editors that we would like to watch out for are Cursor and Windsurf as
+ * they don't yet support working with Resource URIs.
+ *
+ * Ref Cursor: https://forum.cursor.com/t/cursor-mcp-resource-feature-support/50987
+ * JIRA: https://jira.mongodb.org/browse/MCP-104 */
+type AvailableExport = Pick<StoredExport, "exportName" | "exportURI" | "exportPath">;
+
 export type SessionExportsManagerConfig = Pick<
     UserConfig,
     "exportsPath" | "exportTimeoutMs" | "exportCleanupIntervalMs"
@@ -32,7 +55,7 @@ type SessionExportsManagerEvents = {
 };
 
 export class SessionExportsManager extends EventEmitter<SessionExportsManagerEvents> {
-    private sessionExports: Record<Export["name"], Export> = {};
+    private sessionExports: Record<StoredExport["exportName"], StoredExport> = {};
     private exportsCleanupInProgress: boolean = false;
     private exportsCleanupInterval: NodeJS.Timeout;
     private exportsDirectoryPath: string;
@@ -50,10 +73,14 @@ export class SessionExportsManager extends EventEmitter<SessionExportsManagerEve
         );
     }
 
-    public get availableExports(): Export[] {
-        return Object.values(this.sessionExports).filter(
-            ({ createdAt }) => !isExportExpired(createdAt, this.config.exportTimeoutMs)
-        );
+    public get availableExports(): AvailableExport[] {
+        return Object.values(this.sessionExports)
+            .filter(({ exportCreatedAt: createdAt }) => !isExportExpired(createdAt, this.config.exportTimeoutMs))
+            .map(({ exportName, exportURI, exportPath }) => ({
+                exportName,
+                exportURI,
+                exportPath,
+            }));
     }
 
     public async close(): Promise<void> {
@@ -69,27 +96,21 @@ export class SessionExportsManager extends EventEmitter<SessionExportsManagerEve
         }
     }
 
-    public async readExport(exportName: string): Promise<{
-        content: string;
-        exportURI: string;
-    }> {
+    public async readExport(exportName: string): Promise<string> {
         try {
             const exportNameWithExtension = validateExportName(exportName);
             const exportHandle = this.sessionExports[exportNameWithExtension];
             if (!exportHandle) {
                 throw new Error("Requested export has either expired or does not exist!");
             }
 
-            const { path: exportPath, uri, createdAt } = exportHandle;
+            const { exportPath, exportCreatedAt } = exportHandle;
 
-            if (isExportExpired(createdAt, this.config.exportTimeoutMs)) {
+            if (isExportExpired(exportCreatedAt, this.config.exportTimeoutMs)) {
                 throw new Error("Requested export has expired!");
             }
 
-            return {
-                exportURI: uri,
-                content: await fs.readFile(exportPath, "utf8"),
-            };
+            return await fs.readFile(exportPath, "utf8");
         } catch (error) {
             this.logger.error({
                 id: LogId.exportReadError,
@@ -111,10 +132,7 @@ export class SessionExportsManager extends EventEmitter<SessionExportsManagerEve
         input: FindCursor;
         exportName: string;
         jsonExportFormat: JSONExportFormat;
-    }): Promise<{
-        exportURI: string;
-        exportPath: string;
-    }> {
+    }): Promise<AvailableExport> {
         try {
             const exportNameWithExtension = validateExportName(ensureExtension(exportName, "json"));
             const exportURI = `exported-data://${encodeURIComponent(exportNameWithExtension)}`;
@@ -130,6 +148,7 @@ export class SessionExportsManager extends EventEmitter<SessionExportsManagerEve
                 await pipeline([inputStream, ejsonDocStream, outputStream]);
                 pipeSuccessful = true;
                 return {
+                    exportName,
                     exportURI,
                     exportPath: exportFilePath,
                 };
@@ -150,10 +169,10 @@ export class SessionExportsManager extends EventEmitter<SessionExportsManagerEve
                 void input.close();
                 if (pipeSuccessful) {
                     this.sessionExports[exportNameWithExtension] = {
-                        name: exportNameWithExtension,
-                        createdAt: Date.now(),
-                        path: exportFilePath,
-                        uri: exportURI,
+                        exportName: exportNameWithExtension,
+                        exportCreatedAt: Date.now(),
+                        exportPath: exportFilePath,
+                        exportURI: exportURI,
                     };
                     this.emit("export-available", exportURI);
                 }
@@ -211,11 +230,11 @@ export class SessionExportsManager extends EventEmitter<SessionExportsManagerEve
         this.exportsCleanupInProgress = true;
         const exportsForCleanup = { ...this.sessionExports };
         try {
-            for (const { path: exportPath, createdAt, uri, name } of Object.values(exportsForCleanup)) {
-                if (isExportExpired(createdAt, this.config.exportTimeoutMs)) {
-                    delete this.sessionExports[name];
+            for (const { exportPath, exportCreatedAt, exportURI, exportName } of Object.values(exportsForCleanup)) {
+                if (isExportExpired(exportCreatedAt, this.config.exportTimeoutMs)) {
+                    delete this.sessionExports[exportName];
                     await this.silentlyRemoveExport(exportPath);
-                    this.emit("export-expired", uri);
+                    this.emit("export-expired", exportURI);
                 }
             }
         } catch (error) {
diff --git a/src/resources/common/exportedData.ts b/src/resources/common/exportedData.ts
@@ -48,10 +48,10 @@ export class ExportedData {
     private listResourcesCallback: ListResourcesCallback = () => {
         try {
             return {
-                resources: this.server.session.exportsManager.availableExports.map(({ name, uri }) => ({
-                    name: name,
-                    description: this.exportNameToDescription(name),
-                    uri: uri,
+                resources: this.server.session.exportsManager.availableExports.map(({ exportName, exportURI }) => ({
+                    name: exportName,
+                    description: this.exportNameToDescription(exportName),
+                    uri: exportURI,
                     mimeType: "application/json",
                 })),
             };
@@ -70,8 +70,8 @@ export class ExportedData {
     private autoCompleteExportName: CompleteResourceTemplateCallback = (value) => {
         try {
             return this.server.session.exportsManager.availableExports
-                .filter(({ name }) => name.startsWith(value))
-                .map(({ name }) => name);
+                .filter(({ exportName }) => exportName.startsWith(value))
+                .map(({ exportName }) => exportName);
         } catch (error) {
             this.server.session.logger.error({
                 id: LogId.exportedDataAutoCompleteError,
@@ -88,12 +88,12 @@ export class ExportedData {
                 throw new Error("Cannot retrieve exported data, exportName not provided.");
             }
 
-            const { content, exportURI } = await this.server.session.exportsManager.readExport(exportName);
+            const content = await this.server.session.exportsManager.readExport(exportName);
 
             return {
                 contents: [
                     {
-                        uri: exportURI,
+                        uri: url.href,
                         text: content,
                         mimeType: "application/json",
                     },
@@ -104,7 +104,7 @@ export class ExportedData {
                 contents: [
                     {
                         uri: url.href,
-                        text: `Error reading from ${this.uri}: ${error instanceof Error ? error.message : String(error)}`,
+                        text: `Error reading ${url.href}: ${error instanceof Error ? error.message : String(error)}`,
                     },
                 ],
                 isError: true,
diff --git a/src/tools/mongodb/read/export.ts b/src/tools/mongodb/read/export.ts
@@ -66,7 +66,8 @@ export class ExportTool extends MongoDBToolBase {
         ];
 
         // This special case is to make it easier to work with exported data for
-        // stdio transport.
+        // clients that still cannot reference resources (Cursor).
+        // More information here: https://jira.mongodb.org/browse/MCP-104
         if (this.config.transport === "stdio") {
             toolCallContent.push({
                 type: "text",
diff --git a/tests/integration/resources/exportedData.test.ts b/tests/integration/resources/exportedData.test.ts
@@ -32,14 +32,15 @@ describeWithMongoDB(
 
         describe("when requesting non-existent resource", () => {
             it("should return an error", async () => {
+                const exportURI = "exported-data://db.coll.json";
                 await integration.connectMcpClient();
                 const response = await integration.mcpClient().readResource({
-                    uri: "exported-data://db.coll.json",
+                    uri: exportURI,
                 });
                 expect(response.isError).toEqual(true);
-                expect(response.contents[0]?.uri).toEqual("exported-data://db.coll.json");
+                expect(response.contents[0]?.uri).toEqual(exportURI);
                 expect(response.contents[0]?.text).toEqual(
-                    "Error reading from exported-data://{exportName}: Requested export has either expired or does not exist!"
+                    `Error reading ${exportURI}: Requested export has either expired or does not exist!`
                 );
             });
         });
@@ -65,7 +66,7 @@ describeWithMongoDB(
                 expect(response.isError).toEqual(true);
                 expect(response.contents[0]?.uri).toEqual(exportedResourceURI);
                 expect(response.contents[0]?.text).toEqual(
-                    "Error reading from exported-data://{exportName}: Requested export has expired!"
+                    `Error reading ${exportedResourceURI}: Requested export has expired!`
                 );
             });
         });
diff --git a/tests/unit/common/sessionExportsManager.test.ts b/tests/unit/common/sessionExportsManager.test.ts
@@ -87,17 +87,14 @@ describe("SessionExportsManager unit test", () => {
         });
 
         it("should return the resource content", async () => {
-            const { exportName, exportURI } = getExportNameAndPath(session.sessionId, Date.now());
+            const { exportName } = getExportNameAndPath(session.sessionId, Date.now());
             const inputCursor = createDummyFindCursor([]);
             await manager.createJSONExport({
                 input: inputCursor,
                 exportName,
                 jsonExportFormat: "relaxed",
             });
-            expect(await manager.readExport(exportName)).toEqual({
-                content: "[]",
-                exportURI,
-            });
+            expect(await manager.readExport(exportName)).toEqual("[]");
         });
     });
 
@@ -137,16 +134,16 @@ describe("SessionExportsManager unit test", () => {
                 expect(availableExports).toHaveLength(1);
                 expect(availableExports).toContainEqual(
                     expect.objectContaining({
-                        name: exportName,
-                        uri: exportURI,
+                        exportName,
+                        exportURI,
                     })
                 );
 
                 // Emit event
                 expect(emitSpy).toHaveBeenCalledWith("export-available", exportURI);
 
                 // Exports relaxed json
-                const jsonData = JSON.parse((await manager.readExport(exportName)).content) as unknown[];
+                const jsonData = JSON.parse(await manager.readExport(exportName)) as unknown[];
                 expect(jsonData).toEqual([]);
             });
         });
@@ -169,16 +166,16 @@ describe("SessionExportsManager unit test", () => {
                 expect(availableExports).toHaveLength(1);
                 expect(availableExports).toContainEqual(
                     expect.objectContaining({
-                        name: expectedExportName,
-                        uri: `exported-data://${expectedExportName}`,
+                        exportName: expectedExportName,
+                        exportURI: `exported-data://${expectedExportName}`,
                     })
                 );
 
                 // Emit event
                 expect(emitSpy).toHaveBeenCalledWith("export-available", `exported-data://${expectedExportName}`);
 
                 // Exports relaxed json
-                const jsonData = JSON.parse((await manager.readExport(expectedExportName)).content) as unknown[];
+                const jsonData = JSON.parse(await manager.readExport(expectedExportName)) as unknown[];
                 expect(jsonData).toContainEqual(expect.objectContaining({ name: "foo", longNumber: 12 }));
                 expect(jsonData).toContainEqual(expect.objectContaining({ name: "bar", longNumber: 123456 }));
             });
@@ -202,16 +199,16 @@ describe("SessionExportsManager unit test", () => {
                 expect(availableExports).toHaveLength(1);
                 expect(availableExports).toContainEqual(
                     expect.objectContaining({
-                        name: expectedExportName,
-                        uri: `exported-data://${expectedExportName}`,
+                        exportName: expectedExportName,
+                        exportURI: `exported-data://${expectedExportName}`,
                     })
                 );
 
                 // Emit event
                 expect(emitSpy).toHaveBeenCalledWith("export-available", `exported-data://${expectedExportName}`);
 
                 // Exports relaxed json
-                const jsonData = JSON.parse((await manager.readExport(expectedExportName)).content) as unknown[];
+                const jsonData = JSON.parse(await manager.readExport(expectedExportName)) as unknown[];
                 expect(jsonData).toContainEqual(
                     expect.objectContaining({ name: "foo", longNumber: { $numberLong: "12" } })
                 );
@@ -300,8 +297,8 @@ describe("SessionExportsManager unit test", () => {
 
             expect(manager.availableExports).toContainEqual(
                 expect.objectContaining({
-                    name: exportName,
-                    uri: exportURI,
+                    exportName,
+                    exportURI,
                 })
             );
             expect(await fileExists(exportPath)).toEqual(true);
