@mongoosejs/studio 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.7.0
+
+### MCP support for Next.js and Vercel
+
+Mongoose Studio's MCP endpoint now works on Next.js and standalone Vercel Functions, not only Express.
+MCP uses the same defaults as Express: it is enabled by default without an `apiKey`, and with an `apiKey` it requires `mcp: true` and `publicUrl` and uses OAuth.
+
+For Next.js, rename `pages/api/studio.js` to the optional catch-all route `pages/api/studio/[[...studioRoute]].js`.
+The same `vercelAPIRouteHandler()` handles Studio actions at `/api/studio`, MCP at `/api/studio/mcp`, and OAuth metadata at `/api/studio/.well-known/oauth-protected-resource`.
+`withMongooseStudio()` now accepts a second `options` argument with `mcp`, `apiKey`, and `publicUrl`, and adds rewrites so MCP clients connect to `/studio/mcp`:
+
+```javascript
+// next.config.js
+export default withMongooseStudio({ reactStrictMode: true }, {
+  mcp: true,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+});
+
+// pages/api/studio/[[...studioRoute]].js
+export default vercelAPIRouteHandler(db, {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  mcp: true,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+});
+```
+
+For standalone Vercel Functions, keep `api/studio.js` for Studio actions and add `api/studio-mcp.js` using the new `vercelMCPRouteHandler()`:
+
+```javascript
+// api/studio-mcp.js
+const { vercelMCPRouteHandler } = require('@mongoosejs/studio/vercel');
+
+module.exports = vercelMCPRouteHandler(mongoose, {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+});
+```
+
+With an `apiKey` and `mcp: true`, building the frontend with `frontend()` now writes the OAuth protected resource metadata to `frontend/public/.well-known/oauth-protected-resource` and registers `/api/studio-mcp` with the authorization server.
+Copy the frontend only after the `frontend()` promise resolves, and make sure the copy includes hidden directories such as `.well-known`.
+See the README for the full Vercel setup.
+
+### Breaking: Vercel and Next.js handlers without an API key are limited to localhost
+
+`vercelAPIRouteHandler()` now applies the same `bindIp` restriction as the Express integration.
+Without an `apiKey`, Studio API actions and MCP requests are only accepted from localhost by default, and other clients get a 403.
+On Vercel, the client IP comes from the `x-vercel-forwarded-for` header, so a deployed handler without an `apiKey` rejects every request unless you configure `bindIp`.
+
+Set `bindIp` to an IP address or an array of IP addresses to allow specific clients, or set `bindIp: null` to restore the previous behavior of accepting requests from any IP:
+
+```javascript
+const handler = vercelAPIRouteHandler(db, {
+  bindIp: null
+});
+```
+
+Handlers configured with an `apiKey` are unaffected.
+
 ## 0.6.1
 
 ### Safer MCP defaults with API keys

package/README.md

@@ -91,28 +91,109 @@ import withMongooseStudio from '@mongoosejs/studio/next';
 export default withMongooseStudio({
   // Your Next.js config here
   reactStrictMode: true,
+}, {
+  mcp: true,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
 });
 ```
 
-Then, add `pages/api/studio.js` to your Next.js project to host the Mongoose Studio API:
+Add `pages/api/studio/[[...studioRoute]].js` to your Next.js project to host
+both the Mongoose Studio API and MCP. If you already have
+`pages/api/studio.js`, move its handler into the new file and remove the old
+file. The optional catch-all keeps `/api/studio` working for existing Studio
+actions and also accepts `/api/studio/mcp` and the OAuth metadata path.
 
 ```javascript
+// pages/api/studio/[[...studioRoute]].js
 // Make sure to import the database connection
-import db from '../../src/db';
-import studio from '@mongoosejs/studio/backend/next';
+import db from '../../../src/db';
+import { vercelAPIRouteHandler } from '@mongoosejs/studio/vercel';
 
-const handler = studio(
+const handler = vercelAPIRouteHandler(
   db, // Mongoose connection or Mongoose global. Or null to use `import mongoose`.
   {
     apiKey: process.env.MONGOOSE_STUDIO_API_KEY, // optional
     connection: db, // Optional: Connection or Mongoose global. If omitted, will use `import mongoose`
     connectToDB: async () => { /* connection logic here */ }, // Optional: if you need to call a function to connect to the database put it here
+    mcp: true, // Also enabled by default without an API key
+    publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL // Required with an API key; e.g. https://app.example.com/studio
   }
 );
 
 export default handler;
 ```
 
+With `mcp: true`, the same API function handles Streamable HTTP
+at `/studio/mcp`. With an API key, it also serves OAuth discovery at
+`/studio/.well-known/oauth-protected-resource`. `withMongooseStudio` installs
+rewrites from those public URLs to the catch-all API route and shows
+`/studio/mcp` in the frontend. No additional API function or `mcpUrl` setting
+is needed. The rewrites are needed to keep the public URL at `/studio/mcp`;
+the catch-all file itself lives under `/api/studio`. A Pro API key is required
+for OAuth-based Vercel MCP. Without an API key, MCP is enabled by default and
+is limited to localhost unless `bindIp` is configured. Set `bindIp` to an IP
+address or an array of IP addresses to permit other clients; set it to `null`
+to allow access from any IP. The same restriction applies to Studio API actions.
+With an API key, set `publicUrl` to the externally reachable `/studio` URL. The OAuth resource
+URL is derived from it, even if the workspace's `baseUrl` differs.
+
+The handler is stateless and returns a JSON response for each POST. No Redis,
+sticky sessions, or long-lived SSE connection is needed. Tool calls still count
+against Vercel Function duration and payload limits, so set an appropriate
+`maxDuration` for longer database operations and keep results reasonably sized.
+
+### Standalone Vercel Functions
+
+If your project uses `api/studio.js` rather than Next.js, keep it for Studio
+actions and add a separate `api/studio-mcp.js` function for MCP. Next.js
+optional catch-all filenames such as `[[...studioRoute]].js` do not apply to
+standalone Vercel Functions:
+
+```javascript
+// api/studio-mcp.js
+// Make sure to import the database connection
+import db from '../../../src/db';
+const { vercelMCPRouteHandler } = require('@mongoosejs/studio/vercel');
+
+module.exports = vercelMCPRouteHandler(db, {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+});
+```
+
+Set `MONGOOSE_STUDIO_PUBLIC_URL` to the externally reachable Studio URL, for
+example `https://app.example.com/studio`, when using an API key. Without an
+API key, MCP is enabled by default and follows the same localhost and `bindIp`
+restriction described above. Connect MCP clients to `/api/studio-mcp`; no
+rewrite is required.
+
+For OAuth, the protected resource metadata is generated in the Studio frontend
+by the same `frontend()` call used to write `config.js`. It registers the MCP
+resource before the returned promise resolves, so copy the frontend after
+that promise resolves. Existing `publicUrl` fallbacks can stay as they are;
+the copy source must include hidden files:
+
+```javascript
+const { execSync } = require('child_process');
+const opts = {
+  apiKey: process.env.MONGOOSE_STUDIO_API_KEY,
+  mcp: true,
+  publicUrl: process.env.MONGOOSE_STUDIO_PUBLIC_URL
+};
+require('@mongoosejs/studio/frontend')('/api/studio', true, opts).then(() => {
+  execSync('mkdir -p ./public/studio && cp -r ./node_modules/@mongoosejs/studio/frontend/public/. ./public/studio/');
+});
+```
+
+The `/.` source copies hidden directories such as `.well-known`; a `/*` source
+does not. This places `public/studio/.well-known/oauth-protected-resource`
+and registers `/api/studio-mcp` with the authorization server. The metadata is
+needed only with an API key. Set `Content-Type: application/json` and
+`Access-Control-Allow-Origin: *` for that static path, as in the
+[standalone Vercel example](development/movies-vercel/vercel.json). Its
+[build script](development/movies-vercel/build.js) shows the complete asset
+copy and metadata generation sequence.
+
 ### Nest.js
 
 Add `MongooseStudioModule` to your app module as follows.

package/backend/next.js

@@ -1,17 +1,41 @@
 'use strict';
 
 const Backend = require('./');
+const vercelMCP = require('./vercel/vercelMCP');
+const checkVercelBindIp = require('./vercel/checkBindIp');
 const { defaultMothershipURL } = require('../constants');
 
 module.exports = function next(conn, options) {
   options = { ...options };
+  options.mcp = options.mcp ?? !options.apiKey;
+  const checkRequest = checkVercelBindIp(options);
   const backend = Backend(conn, options.studioConnection, options);
+  const mcpHandlers = options.mcp ? vercelMCP(conn, options, backend) : null;
 
   const mothershipUrl = options._mothershipUrl || defaultMothershipURL;
   let workspace = null;
 
   return async function wrappedNextJSFunction(req, res) {
+    if (!checkRequest(req, res)) {
+      return;
+    }
+
+    const route = req.query?.studioRoute;
+    if (route != null && (!Array.isArray(route) || route.length > 0)) {
+      const routePath = Array.isArray(route) ? route.join('/') : null;
+      if (routePath !== 'mcp' && routePath !== '.well-known/oauth-protected-resource') {
+        return res.status(404).json({ message: 'Not found' });
+      }
+      if (!mcpHandlers) {
+        return res.status(404).json({ message: 'Not found' });
+      }
+      return routePath === 'mcp'
+        ? mcpHandlers.endpoint(req, res)
+        : mcpHandlers.metadata(req, res);
+    }
+
     const params = { ...req.query, ...req.body, ...req.params, authorization: req.headers.authorization };
+    delete params.studioRoute;
     const actionName = params?.action;
 
     const authorization = params?.authorization;

package/backend/vercel/checkBindIp.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const isBindIPConnection = require('../helpers/isBindIPConnection');
+const isLocalhostConnection = require('../helpers/isLocalhostConnection');
+const normalizeBindIPOption = require('../helpers/normalizeBindIPOption');
+
+module.exports = function checkVercelBindIp(options) {
+  const hasBindIpOption = options.bindIp != null;
+  const bindIp = normalizeBindIPOption(options.bindIp);
+
+  return function checkRequest(req, res) {
+    if (options.apiKey || bindIp === null) {
+      return true;
+    }
+    const ip = (process.env.VERCEL && req.headers['x-vercel-forwarded-for']) ||
+      req.ip || req.socket?.remoteAddress || '';
+    const allowed = hasBindIpOption
+      ? isBindIPConnection({ ip }, bindIp)
+      : isLocalhostConnection({ ip });
+    if (!allowed) {
+      res.status(403).json({ message: 'Mongoose Studio without an API key only accepts localhost or configured bindIp connections' });
+    }
+    return allowed;
+  };
+};

package/backend/vercel/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../next');

package/backend/vercel/mcpConfig.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { defaultMothershipURL } = require('../../constants');
+
+module.exports = function vercelMCPConfig(options) {
+  if (!options.publicUrl) {
+    throw new Error('Mongoose Studio requires publicUrl when Vercel MCP is enabled with an API key');
+  }
+  const baseUrl = new URL(options.publicUrl);
+  baseUrl.search = '';
+  baseUrl.hash = '';
+  baseUrl.pathname = `${baseUrl.pathname.replace(/\/+$/, '')}/`;
+  const resource = new URL(options._mcpPath || 'mcp', baseUrl).toString();
+  const metadataUrl = new URL('.well-known/oauth-protected-resource', baseUrl).toString();
+  const mothershipUrl = options._mothershipUrl || defaultMothershipURL;
+
+  return {
+    resource,
+    metadataUrl,
+    metadata: {
+      resource,
+      authorization_servers: [new URL(mothershipUrl).origin],
+      scopes_supported: ['mcp'],
+      bearer_methods_supported: ['header'],
+      resource_documentation: 'https://mongoosestudio.app/docs/'
+    }
+  };
+};

package/backend/vercel/vercelMCP.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const Backend = require('../');
+const mcp = require('../mcp');
+const mothership = require('../integrations/mothership');
+const vercelMCPConfig = require('./mcpConfig');
+const { defaultMothershipURL } = require('../../constants');
+
+module.exports = function createVercelMCPHandlers(conn, options, existingBackend) {
+  if (!options.mcp) {
+    throw new Error('Mongoose Studio requires mcp: true for the Vercel MCP handler');
+  }
+  const config = options.apiKey ? vercelMCPConfig(options) : null;
+  const { resource, metadataUrl } = config || {};
+  const mothershipUrl = options._mothershipUrl || defaultMothershipURL;
+  const backend = existingBackend || Backend(conn, options.studioConnection, options);
+  let workspacePromise;
+  let registered = false;
+
+  async function workspace() {
+    if (!workspacePromise) {
+      workspacePromise = fetch(`${mothershipUrl}/getWorkspace`, {
+        method: 'POST',
+        body: JSON.stringify({ apiKey: options.apiKey }),
+        headers: { Authorization: `Bearer ${options.apiKey}`, 'Content-Type': 'application/json' }
+      }).then(async response => {
+        const data = await response.json();
+        if (!response.ok) {
+          throw new Error(data.message || `Mongoose Studio API Key Error ${response.status}`);
+        }
+        options.workspace = data.workspace;
+        return data.workspace;
+      }).catch(err => {
+        workspacePromise = null;
+        throw err;
+      });
+    }
+    return workspacePromise;
+  }
+
+  async function registerResource() {
+    if (registered) {
+      return;
+    }
+    try {
+      await mothership.Workspace.registerMCPResource({ apiKey: options.apiKey, resource }, options);
+      registered = true;
+    } catch (err) {
+      console.warn(`[MONGOOSE STUDIO] Could not register MCP resource ${resource}: ${err.message}`);
+    }
+  }
+
+  function challenge(res, error) {
+    const detail = error ? `, error="invalid_token", error_description="${error.replace(/"/g, '')}"` : '';
+    res.setHeader('WWW-Authenticate', `Bearer resource_metadata="${metadataUrl}"${detail}`);
+  }
+
+  function cors(req, res) {
+    res.setHeader('Access-Control-Allow-Origin', req.headers.origin || '*');
+    res.setHeader('Vary', 'Origin');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, Mcp-Protocol-Version, Mcp-Session-Id, Last-Event-ID');
+    res.setHeader('Access-Control-Expose-Headers', 'WWW-Authenticate, Mcp-Session-Id, Mcp-Protocol-Version');
+    res.setHeader('Access-Control-Max-Age', '86400');
+    if (req.method === 'OPTIONS') {
+      res.status(204).end();
+      return true;
+    }
+    return false;
+  }
+
+  async function metadata(req, res) {
+    if (!options.apiKey) {
+      return res.status(404).json({ message: 'Not found' });
+    }
+    if (cors(req, res)) {
+      return;
+    }
+    if (req.method !== 'GET') {
+      return res.status(405).end();
+    }
+    try {
+      await workspace();
+      await registerResource();
+      res.setHeader('Cache-Control', 'no-store');
+      return res.status(200).json(config.metadata);
+    } catch (err) {
+      return res.status(500).json({ message: err.message });
+    }
+  }
+
+  async function endpoint(req, res) {
+    if (cors(req, res)) {
+      return;
+    }
+    if (!options.apiKey) {
+      return mcp(backend)(req, res);
+    }
+    try {
+      const currentWorkspace = await workspace();
+      const token = `${req.headers.authorization || ''}`.replace(/^Bearer\s+/i, '').trim();
+      if (!token) {
+        await registerResource();
+        challenge(res);
+        return res.status(401).json({ message: 'Not authorized' });
+      }
+
+      let user;
+      let roles;
+      const context = { $workspaceId: currentWorkspace._id };
+      if (token.startsWith('mcp_at_')) {
+        const result = await mothership.MCPOAuthToken.introspectMCPAccessToken({
+          apiKey: options.apiKey, token, resource
+        }, options);
+        user = result.user;
+        roles = result.permissions.roles;
+        context.maxTimeMS = result.permissions.maxTimeMS;
+        context.readPreference = result.permissions.readPreference;
+      } else {
+        const response = await fetch(`${mothershipUrl}/me`, {
+          method: 'POST',
+          body: JSON.stringify({ workspaceId: currentWorkspace._id }),
+          headers: { Authorization: token, 'Content-Type': 'application/json' }
+        });
+        if (!response.ok) {
+          return res.status(response.status).json({ message: 'Not authorized' });
+        }
+        ({ user, roles } = await response.json());
+      }
+      if (!user || !roles) {
+        return res.status(403).json({ message: 'Not authorized' });
+      }
+      req._internals = {
+        ...context,
+        authorization: token,
+        initiatedById: user._id,
+        initiatedBy: user,
+        userId: user._id,
+        roles
+      };
+      return mcp(backend)(req, res);
+    } catch (err) {
+      if (err.status === 401 || err.status === 403) {
+        challenge(res, err.message);
+        return res.status(401).json({ message: err.message });
+      }
+      return res.status(500).json({ message: err.message });
+    }
+  }
+
+  return { endpoint, metadata };
+};

package/backend/vercel/vercelMCPRouteHandler.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const Backend = require('../');
+const checkVercelBindIp = require('./checkBindIp');
+const vercelMCP = require('./vercelMCP');
+
+module.exports = function vercelMCPRouteHandler(conn, options) {
+  options = { ...options, mcp: true, _mcpPath: '/api/studio-mcp' };
+  const checkRequest = checkVercelBindIp(options);
+  const backend = Backend(conn, options.studioConnection, options);
+  const { endpoint } = vercelMCP(conn, options, backend);
+
+  return function wrappedVercelMCPRouteHandler(req, res) {
+    if (!checkRequest(req, res)) {
+      return;
+    }
+    return endpoint(req, res);
+  };
+};

package/docs/mcp-oauth.md

@@ -24,7 +24,7 @@ It publishes metadata that tells clients where the authorization server is, and
 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.
+Access tokens live 24 hours.
 Refresh tokens live 30 days and rotate on every use, so a user does not have to reconnect the client regularly.
 
 ## Authorization grants

package/express.js

@@ -21,7 +21,7 @@ module.exports = async function mongooseStudioExpressApp(apiUrl, conn, options)
   if (options.mcp && options.apiKey && !options.publicUrl) {
     throw new Error('Mongoose Studio requires the publicUrl option when MCP is enabled with an API key');
   }
-  const hasBindIpOption = Object.prototype.hasOwnProperty.call(options, 'bindIp');
+  const hasBindIpOption = options.bindIp != null;
   const bindIp = normalizeBindIPOption(options.bindIp);
 
   const mothershipUrl = options._mothershipUrl || defaultMothershipURL;

package/frontend/index.js

@@ -5,6 +5,8 @@ const fs = require('fs');
 const path = require('path');
 const webpack = require('webpack');
 const { defaultMothershipURL } = require('../constants');
+const mothership = require('../backend/integrations/mothership');
+const vercelMCPConfig = require('../backend/vercel/mcpConfig');
 const webpackConfig = require('./webpack.config');
 const util = require('util');
 
@@ -33,11 +35,18 @@ module.exports = async function frontend(apiUrl, isLambda, options, workspace) {
 
   const { apiKey, ...workspaceData } = workspace || {};
   const workspaceBaseUrl = workspace?.baseUrl?.replace(/\/+$/, '');
+  const publicBaseUrl = options?.publicUrl?.replace(/\/+$/, '') || workspaceBaseUrl;
+  const mcpPath = options?._mcpPath || (isLambda && options?.mcp === true ? '/api/studio-mcp' : null);
+  const mcpEnabled = options?.mcp ?? !options?.apiKey;
   const config = {
     baseURL: apiUrl,
     isLambda,
-    mcp: options?.mcp !== false,
-    mcpUrl: options?.mcp !== false && workspaceBaseUrl ? `${workspaceBaseUrl}/mcp` : null,
+    mcp: mcpEnabled,
+    mcpUrl: mcpEnabled
+      ? mcpPath
+        ? publicBaseUrl ? new URL(mcpPath, `${publicBaseUrl}/`).toString() : mcpPath
+        : publicBaseUrl ? `${publicBaseUrl}/mcp` : null
+      : null,
     mothershipUrl: apiKey ? mothershipUrl : null,
     workspace: workspaceData
   };
@@ -45,6 +54,19 @@ module.exports = async function frontend(apiUrl, isLambda, options, workspace) {
   if (isLambda) {
     const configPath = path.join(__dirname, './public/config.js');
     fs.writeFileSync(configPath, `window.MONGOOSE_STUDIO_CONFIG = ${JSON.stringify(config, null, 2)};`);
+
+    // The caller copies frontend/public after this promise resolves. Put the
+    // protected resource document there so the same copy includes it.
+    const metadataPath = path.join(__dirname, 'public/.well-known/oauth-protected-resource');
+    if (options?.apiKey && options?.mcp === true) {
+      fs.rmSync(metadataPath, { force: true });
+      const mcpConfig = vercelMCPConfig({ ...options, _mcpPath: '/api/studio-mcp' });
+      await mothership.Workspace.registerMCPResource({ apiKey: options.apiKey, resource: mcpConfig.resource }, options);
+      fs.mkdirSync(path.dirname(metadataPath), { recursive: true });
+      fs.writeFileSync(metadataPath, JSON.stringify(mcpConfig.metadata, null, 2));
+    } else {
+      fs.rmSync(metadataPath, { force: true });
+    }
   }
 
   if (options && options.__watch) {