@mongoosejs/studio 0.5.13 → 0.6.0

package/backend/mcp.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StreamableHTTPServerTransport } = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
+
+const archetypeToZodSchema = require('./util/archetypeToZodSchema');
+const authorize = require('./authorize');
+const packageJson = require('../package.json');
+
+// Params that only trusted middleware may set. `maxTimeMS` and `readPreference`
+// are the limits from the caller's authorization, so an MCP client must not be
+// able to name them.
+const reservedParams = new Set([
+  '$workspaceId',
+  'authorization',
+  'initiatedBy',
+  'initiatedById',
+  'maxTimeMS',
+  'readPreference',
+  'roles',
+  'userId'
+]);
+
+const nodeEnv = process.env.NODE_ENV;
+
+module.exports = function mcp(backend) {
+  return async function mongooseStudioMCP(req, res) {
+    if (req.method !== 'POST') {
+      return res.status(405).json({
+        jsonrpc: '2.0',
+        error: { code: -32000, message: 'Method not allowed' },
+        id: null
+      });
+    }
+
+    const server = createServer(backend, req._internals || {}, req);
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true
+    });
+
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: err.message },
+          id: null
+        });
+      }
+    } finally {
+      await transport.close().catch(() => {});
+      await server.close().catch(() => {});
+    }
+  };
+};
+
+function createServer(backend, requestContext, req) {
+  const server = new McpServer({
+    name: 'mongoose-studio' + (nodeEnv ? ` (-${nodeEnv})` : ''),
+    version: packageJson.version
+  });
+
+  for (const namespace of ['Dashboard', 'Model', 'Script']) {
+    for (const [action, actionFn] of Object.entries(backend[namespace])) {
+      const actionName = `${namespace}.${action}`;
+      if (actionFn.mcp === false || !isAuthorized(actionName, requestContext.roles)) {
+        continue;
+      }
+      const tags = actionFn.tags || [];
+      const inputSchema = archetypeToZodSchema(actionFn.paramsType);
+      const internalParams = Object.fromEntries(
+        Object.keys(inputSchema.shape).filter(key => reservedParams.has(key)).map(key => [key, true])
+      );
+      server.registerTool(actionName, {
+        description: actionFn.description || `Run the Mongoose Studio ${actionName} action`,
+        inputSchema: inputSchema.omit(internalParams),
+        annotations: {
+          readOnlyHint: tags.includes('readOnly'),
+          destructiveHint: tags.includes('destructive'),
+          idempotentHint: tags.includes('readOnly')
+        }
+      }, async(args, extra) => {
+        const params = Object.fromEntries(
+          Object.entries(args || {}).filter(([key]) => !reservedParams.has(key))
+        );
+        Object.assign(params, requestContext);
+
+        try {
+          let result = actionFn(params, req, { setHeader: () => {} });
+          if (result != null && typeof result[Symbol.asyncIterator] === 'function') {
+            const chunks = [];
+            const iterator = result[Symbol.asyncIterator]();
+            const abort = () => iterator.return?.();
+            extra.signal.addEventListener('abort', abort);
+            try {
+              for await (const chunk of { [Symbol.asyncIterator]: () => iterator }) {
+                chunks.push(chunk);
+              }
+            } finally {
+              extra.signal.removeEventListener('abort', abort);
+            }
+            result = chunks;
+          } else {
+            result = await result;
+          }
+
+          return { content: [{ type: 'text', text: stringifyResult(result) }] };
+        } catch (err) {
+          return {
+            isError: true,
+            content: [{ type: 'text', text: err?.message || 'Mongoose Studio action failed' }]
+          };
+        }
+      });
+    }
+  }
+
+  return server;
+}
+
+// Only advertise the tools this request is actually allowed to call, so a
+// read-only user or a read-only OAuth grant does not see write tools at all.
+function isAuthorized(actionName, roles) {
+  try {
+    authorize(actionName, roles);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+function stringifyResult(result) {
+  if (typeof result === 'string') {
+    return result;
+  }
+  return JSON.stringify(result ?? null, (_key, value) => typeof value === 'bigint' ? value.toString() : value, 2);
+}

package/backend/netlify.js

@@ -5,15 +5,16 @@ const { toNetlifyFunction } = require('extrovert');
 const { defaultMothershipURL } = require('../constants');
 
 module.exports = function netlify(conn, options) {
-  const backend = Backend(conn, options?.studioConnection, options);
-  const mothershipUrl = options?._mothershipUrl || defaultMothershipURL;
+  options = { ...options };
+  const backend = Backend(conn, options.studioConnection, options);
+  const mothershipUrl = options._mothershipUrl || defaultMothershipURL;
 
   let workspace = null;
 
   return toNetlifyFunction(async function wrappedNetlifyFunction(params) {
     const actionName = params?.action;
     const authorization = params?.authorization;
-    if (options?.apiKey) {
+    if (options.apiKey) {
       if (!authorization) {
         throw new Error('Not authorized');
       }
@@ -36,6 +37,7 @@ module.exports = function netlify(conn, options) {
             return response;
           })
           .then(res => res.json()));
+        options.workspace = workspace;
       }
 
       const { user, roles } = await fetch(`${mothershipUrl}/me?`, {

package/backend/next.js

@@ -4,9 +4,10 @@ const Backend = require('./');
 const { defaultMothershipURL } = require('../constants');
 
 module.exports = function next(conn, options) {
-  const backend = Backend(conn, options?.studioConnection, options);
+  options = { ...options };
+  const backend = Backend(conn, options.studioConnection, options);
 
-  const mothershipUrl = options?._mothershipUrl || defaultMothershipURL;
+  const mothershipUrl = options._mothershipUrl || defaultMothershipURL;
   let workspace = null;
 
   return async function wrappedNextJSFunction(req, res) {
@@ -14,7 +15,7 @@ module.exports = function next(conn, options) {
     const actionName = params?.action;
 
     const authorization = params?.authorization;
-    if (options?.apiKey) {
+    if (options.apiKey) {
       if (!authorization) {
         throw new Error('Not authorized');
       }
@@ -37,6 +38,7 @@ module.exports = function next(conn, options) {
             return response;
           })
           .then(res => res.json()));
+        options.workspace = workspace;
       }
 
       const { user, roles } = await fetch(`${mothershipUrl}/me?`, {

package/backend/sandbox/createSandbox.js

@@ -5,7 +5,7 @@ const mongoose = require('mongoose');
 const vm = require('vm');
 const { createScriptDb } = require('./createScriptDb');
 
-module.exports = function createSandbox({ db }) {
+module.exports = function createSandbox(db, { maxTimeMS, readPreference }) {
   const logs = [];
 
   // db must be a connection, not a Mongoose instance
@@ -13,7 +13,7 @@ module.exports = function createSandbox({ db }) {
     db = db.connection;
   }
 
-  const scriptDb = createScriptDb(db);
+  const scriptDb = createScriptDb(db, { maxTimeMS, readPreference });
   if (!scriptDb.db.Types) {
     scriptDb.db.Types = mongoose.Types;
   }

package/backend/sandbox/createScriptDb.js

@@ -1,8 +1,24 @@
 'use strict';
 
+const omitNullish = require('../helpers/omitNullish');
+
 const wrappedCollections = new WeakSet();
 
+// Read preference only applies to reads, so it is injected for these methods
+// only. Applying it to a write would be meaningless at best and rejected by the
+// driver at worst.
+const readMethods = new Set([
+  'aggregate',
+  'countDocuments',
+  'distinct',
+  'estimatedDocumentCount',
+  'find',
+  'findOne',
+  'listIndexes'
+]);
+
 const collectionMethodOptionsIndex = new Map([
+  ['aggregate', 1],
   ['bulkWrite', 1],
   ['countDocuments', 1],
   ['createIndex', 1],
@@ -21,26 +37,37 @@ const collectionMethodOptionsIndex = new Map([
   ['findOneAndUpdate', 2],
   ['insertMany', 1],
   ['insertOne', 1],
+  ['listIndexes', 0],
   ['rename', 1],
   ['replaceOne', 2],
   ['updateMany', 2],
   ['updateOne', 2]
 ]);
 
-function createScriptDb(db) {
+function createScriptDb(db, options = {}) {
   const sourceConnection = db;
 
   const scriptConnection = sourceConnection.useDb(sourceConnection.name, { useCache: false });
+  // Mongoose useDb() shares the source connection's options object. Copy it
+  // before setting sandbox-only options so the application connection remains untouched.
+  scriptConnection.options = { ...scriptConnection.options };
   scriptConnection.config = {
     ...scriptConnection.config,
     autoCreate: false,
     autoIndex: false
   };
+  if (options.maxTimeMS != null) {
+    scriptConnection.set('maxTimeMS', options.maxTimeMS);
+  }
 
   let dryRunSession = null;
-  const getSession = () => dryRunSession;
-  cloneModels(sourceConnection, scriptConnection, getSession);
-  wrapCollectionAccessors(scriptConnection, getSession);
+  const getOperationOptions = () => ({
+    session: dryRunSession,
+    maxTimeMS: options.maxTimeMS,
+    readPreference: options.readPreference
+  });
+  cloneModels(sourceConnection, scriptConnection, getOperationOptions);
+  wrapCollectionAccessors(scriptConnection, getOperationOptions);
 
   const originalDebug = sourceConnection.options?.debug;
   scriptConnection.set('debug', function() {
@@ -68,14 +95,14 @@ function createScriptDb(db) {
   };
 }
 
-function cloneModels(sourceConnection, scriptConnection, getSession) {
+function cloneModels(sourceConnection, scriptConnection, getOperationOptions) {
   for (const Model of Object.values(sourceConnection.models ?? {})) {
     if (Model?.schema == null || typeof scriptConnection.model !== 'function') {
       continue;
     }
 
     const ClonedModel = scriptConnection.model(Model.modelName, Model.schema, getCollectionName(Model));
-    wrapModelCollections(ClonedModel, getSession);
+    wrapModelCollections(ClonedModel, getOperationOptions);
   }
 }
 
@@ -83,13 +110,13 @@ function getCollectionName(Model) {
   return Model.collection?.collectionName ?? Model.collection?.name ?? Model.$__collection?.collectionName;
 }
 
-function wrapModelCollections(Model, getSession) {
+function wrapModelCollections(Model, getOperationOptions) {
   const collection = Model?.collection ?? Model?.$__collection;
   if (collection == null) {
     return;
   }
 
-  const wrappedCollection = wrapCollection(collection, getSession);
+  const wrappedCollection = wrapCollection(collection, getOperationOptions);
   Model.collection = wrappedCollection;
   Model.$__collection = wrappedCollection;
 
@@ -108,7 +135,7 @@ function setModelCollectionSymbols(target, collection) {
   }
 }
 
-function wrapCollectionAccessors(scriptConnection, getSession) {
+function wrapCollectionAccessors(scriptConnection, getOperationOptions) {
   const wrappedCollectionCache = new WeakMap();
 
   const nativeDb = scriptConnection.db;
@@ -125,19 +152,19 @@ function wrapCollectionAccessors(scriptConnection, getSession) {
           collection.collection = originalDbCollection.call(nativeDb, collection.name);
         }
       }
-      return getOrCreateWrappedCollection(wrappedCollectionCache, collection, getSession);
+      return getOrCreateWrappedCollection(wrappedCollectionCache, collection, getOperationOptions);
     };
   }
 
   if (originalDbCollection != null) {
     nativeDb.collection = function() {
       const collection = originalDbCollection.apply(this, arguments);
-      return getOrCreateWrappedCollection(wrappedCollectionCache, collection, getSession);
+      return getOrCreateWrappedCollection(wrappedCollectionCache, collection, getOperationOptions);
     };
   }
 }
 
-function getOrCreateWrappedCollection(cache, collection, getSession) {
+function getOrCreateWrappedCollection(cache, collection, getOperationOptions) {
   if (collection == null || (typeof collection !== 'object' && typeof collection !== 'function')) {
     return collection;
   }
@@ -147,12 +174,12 @@ function getOrCreateWrappedCollection(cache, collection, getSession) {
   if (cache.has(collection)) {
     return cache.get(collection);
   }
-  const wrapped = wrapCollection(collection, getSession);
+  const wrapped = wrapCollection(collection, getOperationOptions);
   cache.set(collection, wrapped);
   return wrapped;
 }
 
-function wrapCollection(collection, getSession) {
+function wrapCollection(collection, getOperationOptions) {
   if (wrappedCollections.has(collection)) {
     return collection;
   }
@@ -165,15 +192,20 @@ function wrapCollection(collection, getSession) {
     }
 
     wrapped[methodName] = function() {
-      const args = addSessionOption(Array.from(arguments), optionsIndex, getSession());
+      const { session, maxTimeMS, readPreference } = getOperationOptions();
+      const args = addOperationOptions(Array.from(arguments), optionsIndex, {
+        session,
+        maxTimeMS,
+        readPreference: readMethods.has(methodName) ? readPreference : null
+      });
       return method.apply(collection, args);
     };
   }
   return wrapped;
 }
 
-function addSessionOption(args, optionsIndex, session) {
-  if (session == null) {
+function addOperationOptions(args, optionsIndex, { session, maxTimeMS, readPreference }) {
+  if (session == null && maxTimeMS == null && readPreference == null) {
     return args;
   }
 
@@ -184,14 +216,22 @@ function addSessionOption(args, optionsIndex, session) {
   const options = args[optionsIndex];
 
   if (options != null && typeof options !== 'object') {
-    throw new Error('Cannot run dry run on script where options arg is a non-object');
+    if (session != null) {
+      throw new Error('Cannot run dry run on script where options arg is a non-object');
+    }
+    throw new Error('Cannot apply Studio operation options to script where options arg is a non-object');
   }
 
-  if (options?.session != null) {
+  if (session != null && options?.session != null) {
     throw new Error('Cannot run dry run on script that uses sessions');
   }
 
-  args[optionsIndex] = { ...(options ?? {}), session };
+  args[optionsIndex] = omitNullish({
+    ...(options ?? {}),
+    maxTimeMS: maxTimeMS ?? options?.maxTimeMS,
+    readPreference: readPreference ?? options?.readPreference,
+    session: session ?? options?.session
+  });
   return args;
 }
 

package/backend/util/archetypeToZodSchema.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const Archetype = require('archetype');
+const mongoose = require('mongoose');
+const z = require('zod/v4');
+
+module.exports = function archetypeToZodSchema(paramsType) {
+  if (paramsType?.schema?.json == null) {
+    throw new Error('Expected a compiled Archetype params type');
+  }
+
+  return objectToZodSchema(paramsType.schema.json());
+};
+
+function objectToZodSchema(definition) {
+  return z.object(Object.fromEntries(
+    Object.entries(definition).map(([path, options]) => [path, pathToZodSchema(options)])
+  ));
+}
+
+function pathToZodSchema(options) {
+  if (options == null || typeof options !== 'object' || Array.isArray(options)) {
+    options = { $type: options };
+  } else if (!Object.prototype.hasOwnProperty.call(options, '$type')) {
+    options = { $type: Object, $schema: options };
+  }
+
+  let schema = typeToZodSchema(options.$type, options.$schema);
+  if (Array.isArray(options.$enum) && options.$enum.length > 0) {
+    schema = z.union(options.$enum.map(value => z.literal(value)));
+  }
+  if (typeof options.$validate === 'function') {
+    schema = schema.refine(value => {
+      try {
+        options.$validate(value, options);
+        return true;
+      } catch (_) {
+        return false;
+      }
+    });
+  }
+  if (!options.$required || options.$default !== undefined) {
+    schema = schema.optional();
+  }
+  if (options.$default !== undefined && typeof options.$default !== 'function') {
+    schema = schema.meta({ default: options.$default });
+  }
+  return schema;
+}
+
+function typeToZodSchema(type, nestedSchema) {
+  if (Array.isArray(type)) {
+    return z.array(typeToZodSchema(type[0]));
+  }
+  if (type === Archetype.Any) {
+    return z.unknown();
+  }
+  if (type === 'string' || type === String) {
+    return z.string();
+  }
+  if (type === 'number' || type === Number) {
+    return z.number();
+  }
+  if (type === 'boolean' || type === Boolean) {
+    return z.boolean();
+  }
+  if (type === Date || type === mongoose.Types.ObjectId) {
+    return z.string();
+  }
+  if (type === Object) {
+    return nestedSchema ? objectToZodSchema(nestedSchema) : z.record(z.string(), z.unknown());
+  }
+  return z.unknown();
+}

package/docs/mcp-oauth.md

@@ -0,0 +1,106 @@
+# MCP OAuth
+
+Mongoose Studio lets a user connect an MCP client, such as ChatGPT or Claude, to a Studio deployment using OAuth 2.1.
+The client never receives MongoDB credentials, a connection string, or the workspace API key.
+It receives a short-lived access token that only works against one Studio deployment and only does what the user approved.
+
+## Who does what
+
+The Studio deployment in your application is the OAuth *protected resource*.
+The Mongoose Studio mothership is the OAuth *authorization server*.
+
+Studio therefore never issues, stores, or validates MCP tokens by itself.
+It publishes metadata that tells clients where the authorization server is, and it asks the authorization server to resolve each incoming token.
+
+## The flow
+
+1. The user adds the Studio MCP URL, for example `https://app.example.com/studio/mcp`, to ChatGPT or Claude.
+2. The client calls the MCP endpoint with no token and gets a `401` with a `WWW-Authenticate: Bearer resource_metadata="..."` header.
+3. The client fetches that protected resource metadata document from Studio, which names the authorization server and the resource identifier.
+4. The client fetches the authorization server metadata, registers itself dynamically, and opens the Studio authorization page in a browser.
+5. The user signs in to Mongoose Studio if necessary, reviews the access being delegated, adjusts it if they have a choice, and authorizes.
+6. The authorization server redirects back to the client with a single-use authorization code.
+7. The client exchanges the code plus its PKCE verifier for a short-lived access token and a refresh token.
+8. On every MCP request, Studio asks the authorization server to resolve the access token, and runs the request under the policy it returns.
+
+Authorization Code with PKCE (`S256`) is required, and there are no client secrets: MCP clients are public clients.
+Access tokens live 15 minutes.
+Refresh tokens live 30 days and rotate on every use, so a user does not have to reconnect the client regularly.
+
+## Authorization grants
+
+Approving the authorization page creates an `MCPOAuthGrant` on the mothership.
+The grant records who delegated the access, the workspace and Studio deployment it applies to, which OAuth client it was issued to, and the capabilities that were approved:
+
+```javascript
+{
+  userId,
+  workspaceId,
+  resource,       // canonical URL of the Studio MCP endpoint, the environment being accessed
+  oauthClientId,
+  oauthClientName,
+  capabilities: {
+    read: true,
+    write: false,
+    readPreference: 'secondary',
+    maxTimeMS: 5000,
+    collections: '*'
+  },
+  lastUsedAt,
+  revokedAt
+}
+```
+
+A Studio workspace is the organization and project unit, and `resource` identifies the individual deployment, so a grant is scoped to exactly one database environment.
+
+Access tokens are opaque references to a grant, not copies of it.
+Nothing about the policy is embedded in the token, which is what makes the following true:
+
+- Revoking a grant, or revoking the client's refresh token, stops the client immediately.
+- Editing a grant changes what the client may do on its next request, without issuing a new credential.
+- Changing the user's workspace roles or the workspace MCP policy changes what the client may do, again on its next request.
+
+## Effective authorization
+
+The access delegated to an MCP client is the intersection of four things:
+
+1. The workspace `mcpPolicy`.
+2. The member's `mcpPolicy`.
+3. The member's Studio roles.
+4. The capabilities on the grant.
+
+Every layer can only take access away.
+A read-only user cannot delegate write access, a user capped at secondary reads cannot delegate primary reads, and a user capped at 5 seconds cannot delegate 30 seconds.
+The authorization page only offers options that are valid reductions of what the user already has, and the server intersects the request again before storing it, so a tampered request cannot widen a grant.
+
+Studio enforces the resolved policy per request:
+
+- `write: false` downgrades the request's roles, so write actions are neither offered as MCP tools nor callable.
+- `maxTimeMS` and `readPreference` travel as request params, set from the grant by trusted middleware, and every Studio action applies them to its MongoDB operations, including operations inside dashboard and document scripts.
+
+The Studio action tree is built once, with one set of options, so these limits are per request rather than per mount.
+They can only narrow what the host application already allows: `maxTimeMS` is capped by the `maxTimeMS` option when one is configured, and a read preference is resolved to whichever of the configured and requested values is more restrictive.
+`maxTimeMS` and `readPreference` are also reserved MCP params, so they are not offered to MCP clients as tool inputs and a client cannot name them itself.
+
+## Configuration
+
+The Mongoose Studio side needs a Pro API key and its own externally reachable URL, since the resource identifier is that URL.
+Set `publicUrl` to the URL where Mongoose Studio is mounted:
+
+```javascript
+app.use('/studio', await studio('/studio/api', mongoose, {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  publicUrl: 'https://app.example.com/studio'
+}));
+```
+
+Pass `mcp: false` to serve Studio without an MCP endpoint at all.
+Neither the endpoint nor its protected resource metadata is then mounted, so there is nothing for an MCP client to discover.
+Without an API key, the MCP endpoint follows the normal localhost or `bindIp` restrictions and does not mount OAuth protected resource metadata.
+
+Mongoose Studio registers that URL with the authorization server the first time a client asks for its protected resource metadata, which is how an OAuth `resource` parameter is mapped back to a workspace.
+It advertises the configured mothership's origin in `authorization_servers`, keeping authentication with the same service Mongoose Studio already uses.
+
+Browser based MCP clients, claude.ai among them, run discovery from the page rather than from a server.
+Studio therefore serves the MCP endpoint and its metadata with CORS, and exposes `WWW-Authenticate` via `Access-Control-Expose-Headers`.
+Without that last header a browser hides the challenge from the client, and the client cannot find the authorization server at all.

package/eslint.config.js

@@ -13,6 +13,7 @@ module.exports = defineConfig([
       sourceType: 'commonjs',
       globals: {
         fetch: true,
+        URL: true,
         setTimeout: true,
         process: true,
         console: true,

package/eval/agent/run.js

@@ -161,7 +161,7 @@ async function executeFinalCode(conn, trace) {
   if (!trace.finalCode) {
     return;
   }
-  const sandbox = createSandbox({ db: conn });
+  const sandbox = createSandbox(conn, {});
   try {
     trace.output = await sandbox.runScript({ script: trace.finalCode });
     trace.logs = sandbox.getLogs();