backend-manager 5.0.182 → 5.0.184

package/CHANGELOG.md

@@ -14,6 +14,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.0.184] - 2026-03-31
+### Changed
+- Renamed email template shortcuts from `main/` to `core/` prefix across constants and all consumer files
+- Added new templates: `core/plain` and `core/marketing/promotional`
+
 # [5.0.177] - 2026-03-29
 ### Changed
 - `payment-recovered` transition now sends email to internal team only — customer no longer receives a "Payment received" notification

package/CLAUDE.md

@@ -1278,6 +1278,100 @@ assistant.isProduction()   // true when ENVIRONMENT === 'production'
 assistant.isTesting()      // true when running tests (via npx bm test)
 ```
 
+## Model Context Protocol (MCP)
+
+BEM includes a built-in MCP server that exposes BEM routes as tools for Claude Chat, Claude Code, and other MCP clients.
+
+### Architecture
+
+Two transport modes:
+- **Stdio** (local): `npx bm mcp` — for Claude Code / Claude Desktop
+- **Streamable HTTP** (remote): `POST /backend-manager/mcp` — for Claude Chat (stateless, Firebase Functions compatible)
+
+### Available Tools (19)
+
+| Tool | Route | Description |
+|------|-------|-------------|
+| `firestore_read` | `GET /admin/firestore` | Read a Firestore document by path |
+| `firestore_write` | `POST /admin/firestore` | Write/merge a Firestore document |
+| `firestore_query` | `POST /admin/firestore/query` | Query a collection with where/orderBy/limit |
+| `send_email` | `POST /admin/email` | Send transactional email via SendGrid |
+| `send_notification` | `POST /admin/notification` | Send push notification via FCM |
+| `get_user` | `GET /user` | Get authenticated user info |
+| `get_subscription` | `GET /user/subscription` | Get subscription info for a user |
+| `sync_users` | `POST /admin/users/sync` | Sync user data across systems |
+| `list_campaigns` | `GET /marketing/campaign` | List marketing campaigns |
+| `create_campaign` | `POST /marketing/campaign` | Create a marketing campaign |
+| `get_stats` | `GET /admin/stats` | Get system statistics |
+| `cancel_subscription` | `POST /payments/cancel` | Cancel subscription at period end |
+| `refund_payment` | `POST /payments/refund` | Process a refund |
+| `run_cron` | `POST /admin/cron` | Trigger a cron job by ID |
+| `create_post` | `POST /admin/post` | Create a blog post |
+| `create_backup` | `POST /admin/backup` | Create a Firestore backup |
+| `run_hook` | `POST /admin/hook` | Execute a custom hook |
+| `generate_uuid` | `POST /general/uuid` | Generate a UUID |
+| `health_check` | `GET /test/health` | Check server health |
+
+### Authentication
+
+- **Stdio (local):** Reads `BACKEND_MANAGER_KEY` from `functions/.env` automatically
+- **HTTP (remote):** OAuth 2.1 Authorization Code flow with PKCE. Claude Chat handles the flow — user pastes BEM key once on the authorize page. If `OAuth Client ID` is set to the BEM key in the connector config, the authorize step auto-approves.
+
+### Hosting Rewrites
+
+The `npx bm setup` command automatically adds required Firebase Hosting rewrites for MCP OAuth:
+```json
+{
+  "source": "{/backend-manager,/backend-manager/**,/.well-known/oauth-protected-resource,/.well-known/oauth-authorization-server,/authorize,/token}",
+  "function": "bm_api"
+}
+```
+
+### CLI Usage
+
+```bash
+npx bm mcp                    # Start stdio MCP server (for Claude Code)
+```
+
+### Claude Code Configuration
+
+Add to `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "backend-manager": {
+      "command": "npx",
+      "args": ["bm", "mcp"],
+      "cwd": "/path/to/consumer-project"
+    }
+  }
+}
+```
+
+### Claude Chat Configuration
+
+1. Go to Settings → Custom Connectors → Add
+2. **URL:** `https://api.yourdomain.com/backend-manager/mcp`
+3. **OAuth Client ID:** your `BACKEND_MANAGER_KEY` (enables auto-approve)
+4. **OAuth Client Secret:** your `BACKEND_MANAGER_KEY`
+
+### Key Files
+
+| Purpose | File |
+|---------|------|
+| Tool definitions | `src/mcp/tools.js` |
+| HTTP handler (stateless + OAuth) | `src/mcp/handler.js` |
+| Stdio server | `src/mcp/index.js` |
+| HTTP client | `src/mcp/client.js` |
+| CLI command | `src/cli/commands/mcp.js` |
+| MCP route interception | `src/manager/index.js` (`_handleMcp`, `resolveMcpRoutePath`) |
+| Hosting rewrites setup | `src/cli/commands/setup-tests/hosting-rewrites.js` |
+
+### Adding New Tools
+
+1. Add the tool definition to `src/mcp/tools.js` with `name`, `description`, `method`, `path`, and `inputSchema`
+2. The tool automatically maps to the corresponding BEM route via the HTTP client — no handler code needed
+
 ## Response Headers
 
 BEM automatically sets `bm-properties` header with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.182",
+  "version": "5.0.184",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/manager/cron/frequent/abandoned-carts.js

@@ -71,7 +71,7 @@ module.exports = async ({ Manager, assistant, context, libraries }) => {
       email.send({
         sender: 'marketing',
         to: userDoc,
-        template: 'main/order/abandoned-cart',
+        template: 'core/order/abandoned-cart',
         subject: `Complete your ${brandName} ${productName} checkout`,
         categories: ['order/abandoned-cart', `order/abandoned-cart/reminder-${reminderIndex + 1}`],
         copy: false,

package/src/manager/events/firestore/payments-disputes/on-write.js

@@ -225,7 +225,7 @@ function sendDisputeEmail({ alert, match, result, alertId, assistant }) {
     sender: 'internal',
     to: brandEmail,
     subject: subject,
-    template: 'main/basic/card',
+    template: 'core/card',
     categories: ['order/dispute-alert'],
     copy: true,
     data: {

package/src/manager/events/firestore/payments-webhooks/transitions/one-time/purchase-completed.js

@@ -16,7 +16,7 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
   assistant.log(`Transition [one-time/purchase-completed]: uid=${uid}, resourceId=${after.payment?.resourceId}, discount=${hasPromoDiscount ? discount.code : 'none'}`);
 
   sendOrderEmail({
-    template: 'main/order/confirmation',
+    template: 'core/order/confirmation',
     subject: `Your ${brandName} ${productName} order #${order?.id || ''}`,
     categories: ['order/confirmation'],
     userDoc,

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/cancellation-requested.js

@@ -8,7 +8,7 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
   assistant.log(`Transition [subscription/cancellation-requested]: uid=${uid}, product=${after.product?.id}, cancelDate=${after.cancellation?.date?.timestamp}`);
 
   sendOrderEmail({
-    template: 'main/order/cancellation-requested',
+    template: 'core/order/cancellation-requested',
     subject: `Your cancellation is confirmed #${order?.id || ''}`,
     categories: ['order/cancellation-requested'],
     userDoc,

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/new-subscription.js

@@ -18,7 +18,7 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
   assistant.log(`Transition [subscription/new-subscription]: uid=${uid}, product=${after.product?.id}, frequency=${after.payment?.frequency}, trial=${isTrial}, discount=${hasPromoDiscount ? discount.code : 'none'}`);
 
   sendOrderEmail({
-    template: 'main/order/confirmation',
+    template: 'core/order/confirmation',
     subject: `Your ${brandName} ${planName} order #${order?.id || ''}`,
     categories: ['order/confirmation'],
     userDoc,

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/payment-failed.js

@@ -8,7 +8,7 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
   assistant.log(`Transition [subscription/payment-failed]: uid=${uid}, product=${after.product?.id}, previousStatus=${before?.status}`);
 
   sendOrderEmail({
-    template: 'main/order/payment-failed',
+    template: 'core/order/payment-failed',
     subject: `Payment failed for order #${order?.id || ''}`,
     categories: ['order/payment-failed'],
     userDoc,

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/payment-recovered.js

@@ -8,7 +8,7 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
   assistant.log(`Transition [subscription/payment-recovered]: uid=${uid}, product=${after.product?.id}`);
 
   sendOrderEmail({
-    template: 'main/order/payment-recovered',
+    template: 'core/order/payment-recovered',
     subject: `Payment received for order #${order?.id || ''}`,
     categories: ['order/payment-recovered'],
     internalOnly: true,

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/payment-refunded.js

@@ -14,7 +14,7 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
   assistant.log(`Transition [subscription/payment-refunded]: uid=${uid}, product=${after?.product?.id}, amount=${refundDetails?.amount} ${refundDetails?.currency}, reason=${refundDetails?.reason || 'none'}`);
 
   sendOrderEmail({
-    template: 'main/order/refunded',
+    template: 'core/order/refunded',
     subject: `Your payment has been refunded #${order?.id || ''}`,
     categories: ['order/refunded'],
     userDoc,

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/plan-changed.js

@@ -9,7 +9,7 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
   assistant.log(`Transition [subscription/plan-changed]: uid=${uid}, ${before.product?.id} → ${after.product?.id} (${direction})`);
 
   sendOrderEmail({
-    template: 'main/order/plan-changed',
+    template: 'core/order/plan-changed',
     subject: `Your plan has been updated #${order?.id || ''}`,
     categories: ['order/plan-changed'],
     userDoc,

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/subscription-cancelled.js

@@ -13,7 +13,7 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
   const hasFutureExpiry = !isTrial && after.expires?.timestamp && new Date(after.expires.timestamp) > new Date();
 
   sendOrderEmail({
-    template: 'main/order/cancelled',
+    template: 'core/order/cancelled',
     subject: `Your subscription has been cancelled #${order?.id || ''}`,
     categories: ['order/cancelled'],
     userDoc,

package/src/manager/functions/core/actions/api/general/emails/general:download-app-link.js

@@ -13,7 +13,7 @@ module.exports = function (payload, config) {
       sender: 'marketing',
       categories: ['download'],
       subject: `Free ${config.brand.name} download link for ${payload.name || 'you'}!`,
-      template: 'main/misc/app-download-link',
+      template: 'core/misc/app-download-link',
       copy: false,
       data: {},
     }

package/src/manager/libraries/email/constants.js

@@ -8,23 +8,30 @@
 // Template shortcut map — callers use readable paths instead of SendGrid IDs
 // Paths mirror the email website structure: {category}/{subcategory}/{name}
 const TEMPLATES = {
-  // v2 templates
-  'main/basic/card': 'd-1cd2eee44b6340268c964cd7971d49b9',
-  'main/engagement/feedback': 'd-319ab5c9d5074b21926a93562d6f41f6',
-  'main/misc/app-download-link': 'd-fc8b4834d7e1472896fe7e46152029f4',
-  'main/order/confirmation': 'd-5371ac2b4e3b490bbce51bfc2922ece8',
-  'main/order/payment-failed': 'd-e56af0ac62364bfb9e50af02854e2cd3',
-  'main/order/payment-recovered': 'd-d6dbd17a260a4755b34a852ba09c2454',
-  'main/order/cancellation-requested': 'd-78074f3e8c844146bf263b86fc8d5ecf',
-  'main/order/cancelled': 'd-39041132e6b24e5ebf0e95bce2d94dba',
-  'main/order/plan-changed': 'd-399086311bbb48b4b77bc90b20fb9d0a',
-  'main/order/trial-ending': 'd-af8ab499cbfb4d56918b4118f44343b0',
-  'main/order/refunded': 'd-aa47fdbffa2b4ca9b73b6256e963e49f',
-  'main/order/abandoned-cart': 'd-d8b3fa67e2b44b398dc280d0576bf1b7',
+  // Default templates
+  'core/card': 'd-1cd2eee44b6340268c964cd7971d49b9',
+  'core/plain': 'd-1d99985c1f0e40ff99d130c94047b080',
+
+  // Global templates
+  'core/engagement/feedback': 'd-319ab5c9d5074b21926a93562d6f41f6',
+  'core/misc/app-download-link': 'd-fc8b4834d7e1472896fe7e46152029f4',
+  'core/marketing/promotional': 'd-5fbaf210b0aa498e9167dfd8ae8e08d0',
+  'core/order/confirmation': 'd-5371ac2b4e3b490bbce51bfc2922ece8',
+  'core/order/payment-failed': 'd-e56af0ac62364bfb9e50af02854e2cd3',
+  'core/order/payment-recovered': 'd-d6dbd17a260a4755b34a852ba09c2454',
+  'core/order/cancellation-requested': 'd-78074f3e8c844146bf263b86fc8d5ecf',
+  'core/order/cancelled': 'd-39041132e6b24e5ebf0e95bce2d94dba',
+  'core/order/plan-changed': 'd-399086311bbb48b4b77bc90b20fb9d0a',
+  'core/order/trial-ending': 'd-af8ab499cbfb4d56918b4118f44343b0',
+  'core/order/refunded': 'd-aa47fdbffa2b4ca9b73b6256e963e49f',
+  'core/order/abandoned-cart': 'd-d8b3fa67e2b44b398dc280d0576bf1b7',
+
+  // Brand-specific templates are NOT registered here.
+  // Each consuming project should hardcode its own brand-specific template IDs directly.
 };
 
-// "default" resolves to the basic card template
-TEMPLATES['default'] = TEMPLATES['main/basic/card'];
+// "default" resolves to the default card template
+TEMPLATES['default'] = TEMPLATES['core/card'];
 
 // Group shortcut map — SendGrid ASM group IDs
 // Rename these in SendGrid dashboard to match the comments

package/src/manager/routes/general/email/templates/download-app-link.js

@@ -17,7 +17,7 @@ module.exports = function (payload, config) {
       sender: 'marketing',
       categories: ['download'],
       subject: `Free ${config.brand.name} download link for ${payload.name || 'you'}!`,
-      template: 'main/misc/app-download-link',
+      template: 'core/misc/app-download-link',
       copy: false,
       data: {},
     }

package/src/manager/routes/user/signup/post.js

@@ -378,7 +378,7 @@ function sendFeedbackEmail(assistant, uid) {
     sender: 'hello',
     categories: ['engagement/feedback'],
     subject: `Want to share your feedback about ${Manager.config.brand.name}?`,
-    template: 'main/engagement/feedback',
+    template: 'core/engagement/feedback',
     copy: false,
     sendAt: moment().add(10, 'days').unix(),
   })

package/src/mcp/handler.js

@@ -93,7 +93,7 @@ function handleAuthorize(req, res, options) {
   const Manager = options.Manager;
 
   // Auto-approve if client_id matches the BEM key
-  if (isValidKey(client_id, Manager) && redirect_uri) {
+  if (isValidKey(client_id) && redirect_uri) {
     const url = new URL(redirect_uri);
     url.searchParams.set('code', client_id);
     if (state) {
@@ -151,7 +151,7 @@ function handleAuthorize(req, res, options) {
     const redirectUri = body.redirect_uri || '';
     const postState = body.state || '';
 
-    if (!isValidKey(key, Manager)) {
+    if (!isValidKey(key)) {
       res.writeHead(403, { 'Content-Type': 'text/html' });
       res.end('<html><body style="background:#111;color:#e55;font-family:sans-serif;display:flex;align-items:center;justify-content:center;height:100vh"><h2>Invalid key. Go back and try again.</h2></body></html>');
       return;
@@ -188,7 +188,7 @@ function handleToken(req, res, options) {
   const Manager = options.Manager;
 
   // The code, client_secret, or client_id IS the backendManagerKey — validate any
-  if (!isValidKey(code, Manager)) {
+  if (!isValidKey(code)) {
     return sendJson(res, 401, {
       error: 'invalid_grant',
       error_description: 'Invalid authorization code.',
@@ -213,7 +213,7 @@ async function handleMcpProtocol(req, res, options) {
   const authHeader = req.headers.authorization || '';
   const key = authHeader.replace(/^Bearer\s+/i, '');
 
-  if (!isValidKey(key, Manager)) {
+  if (!isValidKey(key)) {
     // Return 401 with OAuth discovery hint
     const protocol = req.headers['x-forwarded-proto'] || req.protocol || 'https';
     const host = req.headers['x-forwarded-host'] || req.headers.host || '';
@@ -321,8 +321,8 @@ async function handleMcpProtocol(req, res, options) {
  * Validate a key against the configured backendManagerKey.
  * Returns false if either the key or the config key is empty/missing.
  */
-function isValidKey(key, Manager) {
-  const configKey = Manager.config?.backendManagerKey;
+function isValidKey(key) {
+  const configKey = process.env.BACKEND_MANAGER_KEY || '';
   return !!key && !!configKey && key === configKey;
 }