@mongoosejs/studio 0.5.14 → 0.6.0

package/backend/actions/Script/getScript.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const Archetype = require('archetype');
+const mongoose = require('mongoose');
+
+const authorize = require('../../authorize');
+const operationOptions = require('../../helpers/operationOptions');
+
+const GetScriptParams = new Archetype({
+  initiatedById: {
+    $type: mongoose.Types.ObjectId
+  },
+  scriptId: {
+    $type: mongoose.Types.ObjectId,
+    $required: true
+  },
+  roles: {
+    $type: ['string']
+  },
+  maxTimeMS: {
+    $type: 'number'
+  }
+}).compile('GetScriptParams');
+
+module.exports = ({ studioConnection, options }) => async function getScript(params) {
+  const { initiatedById, scriptId, roles } = new GetScriptParams(params);
+
+  await authorize('Script.getScript', roles);
+
+  const Script = studioConnection.model('__Studio_Script');
+  const script = await Script.findById(scriptId).setOptions(operationOptions(options, params));
+  if (script == null) {
+    throw new Error('Script not found');
+  }
+  if (initiatedById && script.userId?.toString() !== initiatedById.toString()) {
+    throw new Error('Unauthorized');
+  }
+
+  return { script };
+};
+
+module.exports.paramsType = GetScriptParams;
+module.exports.tags = ['readOnly'];

package/backend/actions/Script/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+exports.createScript = require('./createScript');
+exports.executeScript = require('./executeScript');
+exports.getScript = require('./getScript');

package/backend/actions/Task/cancelTask.js

@@ -2,12 +2,15 @@
 
 const Archetype = require('archetype');
 const mongoose = require('mongoose');
-const omitNullish = require('../../helpers/omitNullish');
+const operationOptions = require('../../helpers/operationOptions');
 
 const CancelTaskParams = new Archetype({
   taskId: {
     $type: mongoose.Types.ObjectId,
     $required: true
+  },
+  maxTimeMS: {
+    $type: 'number'
   }
 }).compile('CancelTaskParams');
 
@@ -17,7 +20,7 @@ module.exports = ({ db, options }) => async function cancelTask(params) {
   const { Task } = db.models;
 
   const task = await Task.findOne({ _id: taskId }).
-    setOptions(omitNullish({ maxTimeMS: options?.maxTimeMS })).
+    setOptions(operationOptions(options, params)).
     orFail();
 
   const cancelledTask = await Task.cancelTask({ _id: taskId });

package/backend/actions/Task/getTaskOverview.js

@@ -2,13 +2,16 @@
 
 const Archetype = require('archetype');
 const escape = require('regexp.escape');
-const omitNullish = require('../../helpers/omitNullish');
+const operationOptions = require('../../helpers/operationOptions');
 
 const GetTaskOverviewParams = new Archetype({
   start: { $type: Date },
   end: { $type: Date },
   status: { $type: 'string' },
-  name: { $type: 'string' }
+  name: { $type: 'string' },
+  maxTimeMS: {
+    $type: 'number'
+  }
 }).compile('GetTaskOverviewParams');
 
 /** Statuses shown on the Task overview page. */
@@ -94,7 +97,7 @@ module.exports = ({ db, options }) => async function getTaskOverview(params) {
     }
   ];
 
-  const [result] = await Task.aggregate(pipeline).option(omitNullish({ maxTimeMS: options?.maxTimeMS }));
+  const [result] = await Task.aggregate(pipeline).option(operationOptions(options, params));
 
   return {
     statusCounts: result.statusCounts?.[0] ?? {},

package/backend/actions/Task/getTasks.js

@@ -2,7 +2,7 @@
 
 const Archetype = require('archetype');
 const escape = require('regexp.escape');
-const omitNullish = require('../../helpers/omitNullish');
+const operationOptions = require('../../helpers/operationOptions');
 
 const GetTasksParams = new Archetype({
   start: { $type: Date },
@@ -10,7 +10,10 @@ const GetTasksParams = new Archetype({
   status: { $type: 'string' },
   name: { $type: 'string' },
   skip: { $type: 'number', $default: 0 },
-  limit: { $type: 'number', $default: 100 }
+  limit: { $type: 'number', $default: 100 },
+  maxTimeMS: {
+    $type: 'number'
+  }
 }).compile('GetTasksParams');
 
 const ALL_STATUSES = ['pending', 'in_progress', 'succeeded', 'failed', 'cancelled', 'unknown'];
@@ -97,7 +100,7 @@ module.exports = ({ db, options }) => async function getTasks(params) {
     }
   ];
 
-  const [result] = await Task.aggregate(pipeline).option(omitNullish({ maxTimeMS: options?.maxTimeMS }));
+  const [result] = await Task.aggregate(pipeline).option(operationOptions(options, params));
   const tasks = result.tasks || [];
   const numDocs = (result.count && result.count[0] && result.count[0].total) || 0;
   const statusCounts = result.statusCounts?.[0] ?? {};

package/backend/actions/Task/getTasksOverTime.js

@@ -1,12 +1,15 @@
 'use strict';
 
 const Archetype = require('archetype');
-const omitNullish = require('../../helpers/omitNullish');
+const operationOptions = require('../../helpers/operationOptions');
 
 const GetTasksOverTimeParams = new Archetype({
   start: { $type: Date },
   end: { $type: Date },
-  bucketSizeMs: { $type: 'number' }
+  bucketSizeMs: { $type: 'number' },
+  maxTimeMS: {
+    $type: 'number'
+  }
 }).compile('GetTasksOverTimeParams');
 
 const TRACKED_STATUSES = ['succeeded', 'failed', 'cancelled'];
@@ -55,7 +58,7 @@ module.exports = ({ db, options }) => async function getTasksOverTime(params) {
     { $sort: { _id: 1 } }
   ];
 
-  const results = await Task.aggregate(pipeline).option(omitNullish({ maxTimeMS: options?.maxTimeMS }));
+  const results = await Task.aggregate(pipeline).option(operationOptions(options, params));
 
   return results.map(r => {
     const bucket = { timestamp: r._id, succeeded: 0, failed: 0, cancelled: 0 };

package/backend/actions/Task/rescheduleTask.js

@@ -2,7 +2,7 @@
 
 const Archetype = require('archetype');
 const mongoose = require('mongoose');
-const omitNullish = require('../../helpers/omitNullish');
+const operationOptions = require('../../helpers/operationOptions');
 
 const RescheduleTaskParams = new Archetype({
   taskId: {
@@ -12,6 +12,9 @@ const RescheduleTaskParams = new Archetype({
   scheduledAt: {
     $type: Date,
     $required: true
+  },
+  maxTimeMS: {
+    $type: 'number'
   }
 }).compile('RescheduleTaskParams');
 
@@ -21,7 +24,7 @@ module.exports = ({ db, options }) => async function rescheduleTask(params) {
   const { Task } = db.models;
 
   const task = await Task.findOne({ _id: taskId }).
-    setOptions(omitNullish({ maxTimeMS: options?.maxTimeMS })).
+    setOptions(operationOptions(options, params)).
     orFail();
 
   if (scheduledAt < Date.now()) {

package/backend/actions/Task/runTask.js

@@ -2,12 +2,15 @@
 
 const Archetype = require('archetype');
 const mongoose = require('mongoose');
-const omitNullish = require('../../helpers/omitNullish');
+const operationOptions = require('../../helpers/operationOptions');
 
 const RunTaskParams = new Archetype({
   taskId: {
     $type: mongoose.Types.ObjectId,
     $required: true
+  },
+  maxTimeMS: {
+    $type: 'number'
   }
 }).compile('RunTaskParams');
 
@@ -17,7 +20,7 @@ module.exports = ({ db, options }) => async function runTask(params) {
   const { Task } = db.models;
 
   const task = await Task.findOne({ _id: taskId }).
-    setOptions(omitNullish({ maxTimeMS: options?.maxTimeMS })).
+    setOptions(operationOptions(options, params)).
     orFail();
 
   const executedTask = await Task.execute(task);

package/backend/actions/index.js

@@ -5,5 +5,6 @@ exports.ChatThread = require('./ChatThread');
 exports.Dashboard = require('./Dashboard');
 exports.getCapabilities = require('./getCapabilities');
 exports.Model = require('./Model');
+exports.Script = require('./Script');
 exports.status = require('./status');
 exports.Task = require('./Task');

package/backend/authorize.js

@@ -14,6 +14,7 @@ const actionsToRequiredRoles = {
   'Dashboard.getDashboards': ['owner', 'admin', 'member', 'readonly', 'dashboards'],
   'Dashboard.updateDashboard': ['owner', 'admin', 'member'],
   'Model.createDocument': ['owner', 'admin', 'member'],
+  'Model.createChatMessage': ['owner', 'admin', 'member'],
   'Model.analyzeSchema': ['owner', 'admin', 'member', 'readonly'],
   'Model.updateDocument': ['owner', 'admin', 'member'],
   'Model.validateDocument': ['owner', 'admin', 'member', 'readonly'],
@@ -24,6 +25,7 @@ const actionsToRequiredRoles = {
   'Model.executeDocumentScript': ['owner', 'admin', 'member'],
   'Model.exportQueryResults': ['owner', 'admin', 'member', 'readonly'],
   'Model.getDocument': ['owner', 'admin', 'member', 'readonly'],
+  'Model.getCollectionInfo': ['owner', 'admin', 'member', 'readonly'],
   'Model.getDocuments': ['owner', 'admin', 'member', 'readonly'],
   'Model.getDocumentsStream': ['owner', 'admin', 'member', 'readonly'],
   'Model.getSuggestedProjection': ['owner', 'admin', 'member', 'readonly'],
@@ -32,7 +34,10 @@ const actionsToRequiredRoles = {
   'Model.listModels': ['owner', 'admin', 'member', 'readonly'],
   'Model.streamDocumentChanges': ['owner', 'admin', 'member', 'readonly'],
   'Model.streamChatMessage': ['owner', 'admin', 'member', 'readonly'],
-  'Model.updateDocuments': ['owner', 'admin', 'member']
+  'Model.updateDocuments': ['owner', 'admin', 'member'],
+  'Script.createScript': ['owner', 'admin', 'member', 'readonly'],
+  'Script.executeScript': ['owner', 'admin', 'member', 'readonly'],
+  'Script.getScript': ['owner', 'admin', 'member', 'readonly']
 };
 
 module.exports = function authorize(action, roles) {

package/backend/db/scriptSchema.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const mongoose = require('mongoose');
+
+const scriptSchema = new mongoose.Schema({
+  script: {
+    type: String,
+    required: true
+  },
+  executionResult: new mongoose.Schema({
+    output: mongoose.Schema.Types.Mixed,
+    logs: String,
+    error: String
+  }, { _id: false }),
+  userId: {
+    type: mongoose.Schema.Types.ObjectId
+  },
+  dryRun: {
+    type: Boolean
+  },
+  executionStartedAt: {
+    type: Date
+  },
+  executionFinishedAt: {
+    type: Date
+  }
+}, { timestamps: true });
+
+module.exports = scriptSchema;

package/backend/helpers/operationOptions.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const omitNullish = require('./omitNullish');
+
+/**
+ * Options to apply to a MongoDB operation: the configured query time limit,
+ * narrowed by any limit the request itself carries.
+ *
+ * Per-request limits arrive as params, which trusted middleware sets from the
+ * caller's authorization: an MCP OAuth grant, for example, caps every operation
+ * the AI client runs. They are intersected with the host application's
+ * configuration rather than replacing it, so a request can only ever ask for
+ * less than the host allows, never more.
+ */
+module.exports = function operationOptions(options, params, extra) {
+  return omitNullish({ ...extra, maxTimeMS: resolveMaxTimeMS(options, params) });
+};
+
+module.exports.resolveMaxTimeMS = resolveMaxTimeMS;
+
+function resolveMaxTimeMS(options, params) {
+  const requested = Number(params?.maxTimeMS);
+  const limits = [options?.maxTimeMS, Number.isFinite(requested) && requested > 0 ? requested : null].
+    filter(limit => limit != null);
+  return limits.length === 0 ? null : Math.min(...limits);
+}

package/backend/helpers/readOperationOptions.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const operationOptions = require('./operationOptions');
+
+const readPreferenceRank = {
+  secondary: 0,
+  secondaryPreferred: 1,
+  primary: 2
+};
+
+/**
+ * Options to apply to a read against the application database: everything
+ * `operationOptions()` resolves, plus the read preference. MCP OAuth grants use
+ * the read preference to keep AI clients off the primary, so like the query time
+ * limit it is resolved to whichever of the configured and requested values is
+ * more restrictive.
+ */
+module.exports = function readOperationOptions(options, params, extra) {
+  return operationOptions(options, params, {
+    ...extra,
+    readPreference: resolveReadPreference(options, params)
+  });
+};
+
+function resolveReadPreference(options, params) {
+  const preferences = [options?.readPreference, params?.readPreference].
+    filter(preference => readPreferenceRank[preference] != null);
+  return preferences.length === 0 ?
+    null :
+    preferences.reduce((result, preference) => readPreferenceRank[preference] < readPreferenceRank[result] ? preference : result);
+}

package/backend/index.js

@@ -8,6 +8,7 @@ const chatMessageSchema = require('./db/chatMessageSchema');
 const chatThreadSchema = require('./db/chatThreadSchema');
 const dashboardSchema = require('./db/dashboardSchema');
 const dashboardResultSchema = require('./db/dashboardResultSchema');
+const scriptSchema = require('./db/scriptSchema');
 
 module.exports = function backend(db, studioConnection, options) {
   db = db || mongoose.connection;
@@ -20,6 +21,7 @@ module.exports = function backend(db, studioConnection, options) {
   studioConnection.model('__Studio_DashboardResult', dashboardResultSchema, 'studio__dashboardResults');
   studioConnection.model('__Studio_ChatMessage', chatMessageSchema, 'studio__chatMessages');
   studioConnection.model('__Studio_ChatThread', chatThreadSchema, 'studio__chatThreads');
+  studioConnection.model('__Studio_Script', scriptSchema, 'studio__scripts');
 
   let changeStream = null;
   if (options?.changeStream) {

package/backend/integrations/mothership.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { defaultMothershipURL } = require('../../constants');
+
+async function post(path, params, options) {
+  const mothershipUrl = options?._mothershipUrl || defaultMothershipURL;
+  const mcpOAuthUrl = `${new URL(mothershipUrl).origin}/mcp-oauth`;
+  const response = await fetch(`${mcpOAuthUrl}/${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(params)
+  });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const error = new Error(data?.message || `Mothership request failed with status ${response.status}`);
+    error.status = response.status;
+    throw error;
+  }
+  return data;
+}
+
+exports.MCPOAuthToken = {
+  introspectMCPAccessToken: (params, options) => post('MCPOAuthToken/introspectMCPAccessToken', params, options)
+};
+
+exports.Workspace = {
+  registerMCPResource: (params, options) => post('Workspace/registerMCPResource', params, options)
+};

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, maxTimeMS }) {
+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, maxTimeMS }) {
     db = db.connection;
   }
 
-  const scriptDb = createScriptDb(db, { maxTimeMS });
+  const scriptDb = createScriptDb(db, { maxTimeMS, readPreference });
   if (!scriptDb.db.Types) {
     scriptDb.db.Types = mongoose.Types;
   }