backend-manager 5.0.179 → 5.0.180

package/TODO-CHARGEBLAST.md

@@ -0,0 +1,32 @@
+As for the AMEX enrollment, AMEX alerts are not supported on Stripe/Shopify. To enable them, you’ll need a dedicated AMEX MID and a payment orchestrator to route all AMEX transactions through that dedicated MID. Using a dedicated AMEX MID allows for a dispute rate of up to 5%, so routing all AMEX traffic through it will significantly reduce your dispute rate on Stripe.
+
+06:44 PM
+For Discover,
+
+In order to enroll in Discover coverage, you will need to do the following:
+
+First, provide us with details about your business below:
+- Merchant Legal Name:
+- Merchant DBA Name:
+- Merchant Registered Street Address:
+- City:
+- Country:
+- State/Province:
+- ZIP/Postal Code:
+
+Second, you must request from your payment processor’s support for a few pieces of information. To do so, please follow the steps below and send them the email template below.
+
+""I am enrolling for Discover Ethoca Alerts via my third-party vendor, Chargeblast. I need my 15-Digit Discover SE number. Can you please provide these pieces of information to me ASAP? Let me know if you need any additional info from me. Please feel free to provide me with these pieces of information piecemeal.”
+
+06:44 PM
+For AMEX If you’d like to proceed with obtaining a dedicated AMEX MID, we’d be happy to arrange an introduction for you.
+
+06:45 PM
+Avatar of Zander
+Zander
+Are we still connected?
+
+06:56 PM
+Avatar of Zander
+Zander
+Since this chat has been inactive, I’ll close it for now. If you have more questions, feel free to contact us at any time. Have a great day ahead!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.179",
+  "version": "5.0.180",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {
@@ -48,6 +48,7 @@
     "@firebase/rules-unit-testing": "^5.0.0",
     "@google-cloud/pubsub": "^5.3.0",
     "@google-cloud/storage": "^7.19.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@octokit/rest": "^19.0.13",
     "@sendgrid/mail": "^8.1.6",
     "@sentry/node": "^6.19.7",

package/src/cli/commands/mcp.js

@@ -0,0 +1,32 @@
+const path = require('path');
+const BaseCommand = require('./base-command');
+
+class McpCommand extends BaseCommand {
+  async execute() {
+    const self = this;
+    const functionsDir = path.join(self.firebaseProjectPath, 'functions');
+
+    // Load .env from functions directory so BACKEND_MANAGER_KEY is available
+    const jetpack = require('fs-jetpack');
+    const envPath = path.join(functionsDir, '.env');
+    if (jetpack.exists(envPath)) {
+      require('dotenv').config({ path: envPath });
+    }
+
+    // Resolve the BEM server URL
+    const baseUrl = self.argv.url
+      || process.env.BEM_URL
+      || 'http://localhost:5002';
+
+    // Resolve the admin key
+    const backendManagerKey = self.argv.key
+      || process.env.BACKEND_MANAGER_KEY
+      || '';
+
+    const { startServer } = require('../../mcp/index.js');
+
+    await startServer({ baseUrl, backendManagerKey });
+  }
+}
+
+module.exports = McpCommand;

package/src/cli/index.js

@@ -29,6 +29,7 @@ const StripeCommand = require('./commands/stripe');
 const FirestoreCommand = require('./commands/firestore');
 const AuthCommand = require('./commands/auth');
 const LogsCommand = require('./commands/logs');
+const McpCommand = require('./commands/mcp');
 
 function Main() {}
 
@@ -152,6 +153,12 @@ Main.prototype.process = async function (args) {
     const cmd = new LogsCommand(self);
     return await cmd.execute();
   }
+
+  // MCP server
+  if (self.options['mcp']) {
+    const cmd = new McpCommand(self);
+    return await cmd.execute();
+  }
 };
 
 // Test method for setup command

package/src/manager/events/auth/before-create.js

@@ -1,5 +1,5 @@
 const ERROR_TOO_MANY_ATTEMPTS = 'You have created too many accounts with our service. Please try again later.';
-const MAX_SIGNUPS_PER_DAY = 3;
+const MAX_SIGNUPS_PER_DAY = 2;
 
 /**
  * beforeUserCreated - IP Rate Limiting ONLY

package/src/manager/index.js

@@ -431,6 +431,19 @@ Manager.prototype._preProcess = function (mod) {
   });
 };
 
+Manager.prototype._handleMcp = function (req, res, routePath) {
+  const self = this;
+  const cors = self.libraries.cors;
+
+  return cors(req, res, async () => {
+    const { handleMcpRoute } = require('../mcp/handler.js');
+    await handleMcpRoute(req, res, {
+      Manager: self,
+      routePath: routePath,
+    });
+  });
+};
+
 Manager.prototype._processMiddleware = function (req, res, routePath) {
   const self = this;
 
@@ -779,6 +792,14 @@ Manager.prototype.setupFunctions = function (exporter, options) {
   .https.onRequest(async (req, res) => {
     const route = self.BemRouter(req, res).resolve();
 
+    // MCP endpoint — bypass middleware, handle protocol directly
+    if (route.routePath === 'mcp'
+      || route.routePath.startsWith('mcp/')
+      || route.routePath === '.well-known/oauth-protected-resource'
+      || route.routePath === '.well-known/oauth-authorization-server') {
+      return self._handleMcp(req, res, route.routePath);
+    }
+
     if (route.isLegacy) {
       // Legacy command-based API -> goes through api.js + _process() for hooks
       return self._process((new (require(`${core}/actions/api.js`))()).init(self, { req, res }));

package/src/manager/libraries/disposable-domains.json

@@ -4,6 +4,7 @@
   "0815.ru",
   "0clickemail.com",
   "10mail.org",
+  "10mail.xyz",
   "10minutemail.com",
   "10minutemail.net",
   "123-m.com",
@@ -47,8 +48,8 @@
   "9mail.cf",
   "a-bc.net",
   "agedmail.com",
-  "aji.kr",
   "ajaxapp.net",
+  "aji.kr",
   "alivance.com",
   "amilegit.com",
   "amiri.net",
@@ -186,6 +187,9 @@
   "emailxfer.com",
   "emeil.in",
   "emeil.ir",
+  "emlhub.com",
+  "emlpro.com",
+  "emltmp.com",
   "emz.net",
   "enterto.com",
   "ephemail.net",
@@ -219,10 +223,12 @@
   "flyspam.com",
   "fr33mail.info",
   "frapmail.com",
+  "freeml.net",
   "friendlymail.co.uk",
   "front14.org",
   "fuckingduh.com",
   "fudgerub.com",
+  "fun4k.com",
   "fux0ringduh.com",
   "garliclife.com",
   "gehensiull.com",
@@ -384,8 +390,8 @@
   "maildrop.ml",
   "maildu.de",
   "maildx.com",
-  "mailed.ro",
   "maileater.com",
+  "mailed.ro",
   "mailexpire.com",
   "mailfa.tk",
   "mailforspam.com",
@@ -440,6 +446,7 @@
   "mailzilla.org",
   "makemetheking.com",
   "manybrain.com",
+  "maximail.fyi",
   "mbx.cc",
   "mega.zik.dj",
   "meinspamschutz.de",
@@ -447,7 +454,9 @@
   "messagebeamer.de",
   "mezimages.net",
   "mierdamail.com",
+  "mimimail.me",
   "ministry-of-silly-walks.de",
+  "minitts.net",
   "mintemail.com",
   "misterpinball.de",
   "mmmmail.com",
@@ -503,6 +512,7 @@
   "nurfuerspam.de",
   "nus.edu.sg",
   "nwldx.com",
+  "oakon.com",
   "objectmail.com",
   "obobbo.com",
   "odnorazovoe.ru",
@@ -520,6 +530,9 @@
   "ovpn.to",
   "owlpic.com",
   "pancakemail.com",
+  "pastryofistanbul.com",
+  "pickmail.org",
+  "pickmemail.com",
   "pjjkp.com",
   "plexolan.de",
   "poczta.onet.pl",
@@ -568,6 +581,7 @@
   "selfdestructingmail.com",
   "senseless-entertainment.com",
   "server.ms.selfip.net",
+  "sharebot.net",
   "sharklasers.com",
   "shieldedmail.com",
   "shieldemail.com",
@@ -655,6 +669,7 @@
   "spamtroll.net",
   "speed.1s.fr",
   "spoofmail.de",
+  "spymail.one",
   "squizzy.de",
   "ssoia.com",
   "startkeys.com",
@@ -680,6 +695,7 @@
   "talkinator.com",
   "tapchicuoihoi.com",
   "teewars.org",
+  "teihu.com",
   "teleosaurs.xyz",
   "teleworm.com",
   "teleworm.us",
@@ -720,8 +736,8 @@
   "throwawaymail.com",
   "tilien.com",
   "tittbit.in",
-  "tmailinator.com",
   "tmail.ws",
+  "tmailinator.com",
   "toiea.com",
   "toomail.biz",
   "topranklist.de",
@@ -817,6 +833,7 @@
   "yeah.net",
   "yep.it",
   "yogamaven.com",
+  "yomail.info",
   "yopmail.com",
   "yopmail.fr",
   "yopmail.gq",

package/src/mcp/client.js

@@ -0,0 +1,64 @@
+/**
+ * BEM HTTP Client
+ *
+ * Makes authenticated HTTP calls to a running BEM server (local or production).
+ */
+const fetch = require('wonderful-fetch');
+
+class BEMClient {
+  constructor(options) {
+    options = options || {};
+
+    this.baseUrl = (options.baseUrl || '').replace(/\/+$/, '');
+    this.backendManagerKey = options.backendManagerKey || '';
+  }
+
+  /**
+   * Call a BEM route
+   * @param {string} method - HTTP method (GET, POST, PUT, DELETE)
+   * @param {string} path - Route path (e.g. "admin/firestore")
+   * @param {object} params - Request parameters
+   * @returns {object} - Parsed response
+   */
+  async call(method, path, params) {
+    params = params || {};
+    method = method.toUpperCase();
+
+    const url = new URL(`${this.baseUrl}/backend-manager/${path}`);
+
+    const fetchOptions = {
+      method: method,
+      response: 'json',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      timeout: 120000,
+    };
+
+    if (method === 'GET') {
+      // GET: auth + params go in query string
+      url.searchParams.set('backendManagerKey', this.backendManagerKey);
+
+      for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null) {
+          continue;
+        }
+
+        // Serialize objects/arrays as JSON strings for query params
+        url.searchParams.set(key, typeof value === 'object' ? JSON.stringify(value) : value);
+      }
+    } else {
+      // POST/PUT/DELETE: auth + params go in body
+      fetchOptions.body = JSON.stringify({
+        backendManagerKey: this.backendManagerKey,
+        ...params,
+      });
+    }
+
+    const response = await fetch(url.toString(), fetchOptions);
+
+    return response;
+  }
+}
+
+module.exports = BEMClient;

package/src/mcp/handler.js

@@ -0,0 +1,342 @@
+/**
+ * MCP HTTP Handler (Stateless + OAuth)
+ *
+ * Routes all MCP-related requests:
+ * - OAuth discovery (.well-known endpoints)
+ * - OAuth authorize + token (wraps backendManagerKey as OAuth token)
+ * - MCP protocol (stateless Streamable HTTP transport)
+ *
+ * Compatible with serverless environments like Firebase Functions.
+ * No tokens stored — the backendManagerKey IS the access token.
+ */
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StreamableHTTPServerTransport } = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
+const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+const tools = require('./tools.js');
+const BEMClient = require('./client.js');
+const packageJSON = require('../../package.json');
+
+// Build tool lookup once
+const toolMap = {};
+for (const tool of tools) {
+  toolMap[tool.name] = tool;
+}
+
+/**
+ * Route all MCP-related requests
+ *
+ * @param {IncomingMessage} req
+ * @param {ServerResponse} res
+ * @param {object} options
+ * @param {object} options.Manager - BEM Manager instance
+ * @param {string} options.routePath - Resolved route path (e.g. "mcp", "mcp/authorize")
+ */
+async function handleMcpRoute(req, res, options) {
+  const { Manager, routePath } = options;
+  // Build base URL from the incoming request so discovery URLs match however the client reached us
+  // (ngrok, production domain, localhost, etc.)
+  const protocol = req.headers['x-forwarded-proto'] || req.protocol || 'https';
+  const host = req.headers['x-forwarded-host'] || req.headers.host || '';
+  const baseUrl = `${protocol}://${host}`;
+
+  // --- OAuth Discovery ---
+  if (routePath === '.well-known/oauth-protected-resource') {
+    return sendJson(res, 200, {
+      resource: `${baseUrl}/backend-manager/mcp`,
+      authorization_servers: [
+        `${baseUrl}/backend-manager/mcp`,
+      ],
+    });
+  }
+
+  if (routePath === '.well-known/oauth-authorization-server') {
+    return sendJson(res, 200, {
+      issuer: `${baseUrl}/backend-manager/mcp`,
+      authorization_endpoint: `${baseUrl}/backend-manager/mcp/authorize`,
+      token_endpoint: `${baseUrl}/backend-manager/mcp/token`,
+      response_types_supported: ['code'],
+      grant_types_supported: ['authorization_code'],
+      code_challenge_methods_supported: ['S256'],
+      token_endpoint_auth_methods_supported: ['none'],
+    });
+  }
+
+  // --- OAuth Authorize ---
+  if (routePath === 'mcp/authorize') {
+    return handleAuthorize(req, res, options);
+  }
+
+  // --- OAuth Token ---
+  if (routePath === 'mcp/token') {
+    return handleToken(req, res, options);
+  }
+
+  // --- MCP Protocol ---
+  if (routePath === 'mcp') {
+    return handleMcpProtocol(req, res, options);
+  }
+
+  sendJson(res, 404, { error: 'Not found' });
+}
+
+/**
+ * OAuth Authorize
+ *
+ * If client_id matches the BEM key, auto-redirects immediately (no form).
+ * Otherwise, shows a simple form to enter the key manually.
+ *
+ * To skip the manual step, set OAuth Client ID = YOUR_BEM_KEY in Claude Chat.
+ */
+function handleAuthorize(req, res, options) {
+  const query = req.query || {};
+  const { redirect_uri, state, client_id } = query;
+  const Manager = options.Manager;
+
+  // Auto-approve if client_id matches the BEM key
+  if (isValidKey(client_id, Manager) && redirect_uri) {
+    const url = new URL(redirect_uri);
+    url.searchParams.set('code', client_id);
+    if (state) {
+      url.searchParams.set('state', state);
+    }
+    res.writeHead(302, { Location: url.toString() });
+    res.end();
+    return;
+  }
+
+  if (req.method === 'GET') {
+    // Show a simple authorize form (fallback when client_id is not the BEM key)
+    const html = `<!DOCTYPE html>
+<html>
+<head>
+  <title>Backend Manager — Authorize MCP</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, system-ui, sans-serif; background: #111; color: #eee; display: flex; align-items: center; justify-content: center; min-height: 100vh; }
+    .card { background: #1a1a1a; border: 1px solid #333; border-radius: 12px; padding: 32px; max-width: 420px; width: 100%; }
+    h1 { font-size: 20px; margin-bottom: 8px; }
+    p { font-size: 14px; color: #999; margin-bottom: 24px; }
+    label { font-size: 13px; color: #aaa; display: block; margin-bottom: 6px; }
+    input[type="password"] { width: 100%; padding: 10px 12px; background: #222; border: 1px solid #444; border-radius: 6px; color: #eee; font-size: 14px; }
+    input[type="password"]:focus { outline: none; border-color: #7c6df0; }
+    button { margin-top: 20px; width: 100%; padding: 10px; background: #7c6df0; color: #fff; border: none; border-radius: 6px; font-size: 14px; cursor: pointer; }
+    button:hover { background: #6b5de0; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Authorize MCP Connection</h1>
+    <p>Enter your Backend Manager key to allow Claude to connect.</p>
+    <form method="POST">
+      <input type="hidden" name="redirect_uri" value="${escapeHtml(redirect_uri || '')}">
+      <input type="hidden" name="state" value="${escapeHtml(state || '')}">
+      <label for="key">Backend Manager Key</label>
+      <input type="password" id="key" name="key" placeholder="Enter your key" required autofocus>
+      <button type="submit">Allow</button>
+    </form>
+  </div>
+</body>
+</html>`;
+
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(html);
+    return;
+  }
+
+  // POST — validate key and redirect back with code
+  if (req.method === 'POST') {
+    const body = req.body || {};
+    const key = body.key || '';
+    const redirectUri = body.redirect_uri || '';
+    const postState = body.state || '';
+
+    if (!isValidKey(key, Manager)) {
+      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;
+    }
+
+    if (!redirectUri) {
+      return sendJson(res, 400, { error: 'Missing redirect_uri' });
+    }
+
+    const url = new URL(redirectUri);
+    url.searchParams.set('code', key);
+    if (postState) {
+      url.searchParams.set('state', postState);
+    }
+
+    res.writeHead(302, { Location: url.toString() });
+    res.end();
+    return;
+  }
+
+  sendJson(res, 405, { error: 'Method not allowed' });
+}
+
+/**
+ * OAuth Token — exchanges the auth code (BEM key) for an access token (same BEM key)
+ */
+function handleToken(req, res, options) {
+  if (req.method !== 'POST') {
+    return sendJson(res, 405, { error: 'Method not allowed' });
+  }
+
+  const body = req.body || {};
+  const code = body.code || body.client_secret || body.client_id || '';
+  const Manager = options.Manager;
+
+  // The code, client_secret, or client_id IS the backendManagerKey — validate any
+  if (!isValidKey(code, Manager)) {
+    return sendJson(res, 401, {
+      error: 'invalid_grant',
+      error_description: 'Invalid authorization code.',
+    });
+  }
+
+  // Return the key as the access token — no storage needed
+  sendJson(res, 200, {
+    access_token: code,
+    token_type: 'Bearer',
+    scope: 'tools',
+  });
+}
+
+/**
+ * MCP Protocol — stateless Streamable HTTP transport
+ */
+async function handleMcpProtocol(req, res, options) {
+  const { Manager } = options;
+
+  // Authenticate via Bearer token
+  const authHeader = req.headers.authorization || '';
+  const key = authHeader.replace(/^Bearer\s+/i, '');
+
+  if (!isValidKey(key, Manager)) {
+    // 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 || '';
+    const baseUrl = `${protocol}://${host}`;
+    res.writeHead(401, {
+      'Content-Type': 'application/json',
+      'WWW-Authenticate': `Bearer resource_metadata="${baseUrl}/backend-manager/.well-known/oauth-protected-resource"`,
+    });
+    res.end(JSON.stringify({ error: 'Unauthorized' }));
+    return;
+  }
+
+  // Only POST supported in stateless mode
+  if (req.method !== 'POST') {
+    if (req.method === 'DELETE') {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    return sendJson(res, 405, {
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Method not allowed. Use POST.' },
+    });
+  }
+
+  // Determine the API URL for internal HTTP calls
+  const apiUrl = Manager.project?.apiUrl || 'http://localhost:5002';
+  const client = new BEMClient({ baseUrl: apiUrl, backendManagerKey: key });
+
+  // Create a fresh stateless transport
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  });
+
+  // Create MCP server
+  const server = new Server(
+    {
+      name: 'backend-manager',
+      version: packageJSON.version,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  );
+
+  // List tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      })),
+    };
+  });
+
+  // Call tools
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = toolMap[name];
+
+    if (!tool) {
+      return {
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+    }
+
+    try {
+      const response = await client.call(tool.method, tool.path, args || {});
+
+      const text = typeof response === 'string'
+        ? response
+        : JSON.stringify(response, null, 2);
+
+      return {
+        content: [{ type: 'text', text }],
+      };
+    } catch (error) {
+      const message = error.response
+        ? JSON.stringify(error.response, null, 2)
+        : error.message;
+
+      return {
+        content: [{ type: 'text', text: `Error calling ${tool.path}: ${message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  // Connect and handle
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+
+  // Clean up
+  await transport.close();
+  await server.close();
+}
+
+// --- Helpers ---
+
+/**
+ * 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;
+  return !!key && !!configKey && key === configKey;
+}
+
+function sendJson(res, code, data) {
+  res.writeHead(code, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data));
+}
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+module.exports = { handleMcpRoute };

package/src/mcp/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+/**
+ * BEM MCP Server
+ *
+ * Exposes Backend Manager routes as MCP tools so Claude (or any MCP client)
+ * can interact with a running BEM instance — local or production.
+ *
+ * Usage:
+ *   npx bm mcp
+ *
+ * Environment variables:
+ *   BEM_URL              - BEM server URL (default: http://localhost:5002)
+ *   BACKEND_MANAGER_KEY  - Admin API key for authentication
+ */
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+const BEMClient = require('./client.js');
+const tools = require('./tools.js');
+const packageJSON = require('../../package.json');
+
+/**
+ * Start the MCP server
+ * @param {object} options
+ * @param {string} options.baseUrl - BEM server URL
+ * @param {string} options.backendManagerKey - Admin API key
+ */
+async function startServer(options) {
+  options = options || {};
+
+  const baseUrl = options.baseUrl
+    || process.env.BEM_URL
+    || 'http://localhost:5002';
+  const backendManagerKey = options.backendManagerKey
+    || process.env.BACKEND_MANAGER_KEY
+    || '';
+
+  if (!backendManagerKey) {
+    console.error('[BEM MCP] Warning: No BACKEND_MANAGER_KEY set. Admin routes will fail.');
+  }
+
+  const client = new BEMClient({ baseUrl, backendManagerKey });
+
+  // Create the MCP server
+  const server = new Server(
+    {
+      name: 'backend-manager',
+      version: packageJSON.version,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  );
+
+  // Build a lookup map for tool definitions
+  const toolMap = {};
+  for (const tool of tools) {
+    toolMap[tool.name] = tool;
+  }
+
+  // Handle tools/list — return all tool definitions
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      })),
+    };
+  });
+
+  // Handle tools/call — execute the requested tool
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = toolMap[name];
+
+    if (!tool) {
+      return {
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+    }
+
+    try {
+      const response = await client.call(tool.method, tool.path, args || {});
+
+      // Format the response for the LLM
+      const text = typeof response === 'string'
+        ? response
+        : JSON.stringify(response, null, 2);
+
+      return {
+        content: [{ type: 'text', text }],
+      };
+    } catch (error) {
+      const message = error.response
+        ? JSON.stringify(error.response, null, 2)
+        : error.message;
+
+      return {
+        content: [{ type: 'text', text: `Error calling ${tool.path}: ${message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  // Connect via stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Log to stderr (stdout is reserved for MCP protocol)
+  console.error(`[BEM MCP] Server running — connected to ${baseUrl}`);
+  console.error(`[BEM MCP] ${tools.length} tools available`);
+}
+
+// Allow direct execution or require
+if (require.main === module) {
+  startServer().catch((error) => {
+    console.error('[BEM MCP] Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+module.exports = { startServer };

package/src/mcp/tools.js

@@ -0,0 +1,359 @@
+/**
+ * MCP Tool Definitions
+ *
+ * Each tool maps to a BEM route with method, path, and JSON Schema for inputs.
+ */
+module.exports = [
+  // --- Firestore ---
+  {
+    name: 'firestore_read',
+    description: 'Read a Firestore document by path (e.g. "users/abc123")',
+    method: 'GET',
+    path: 'admin/firestore',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Firestore document path (e.g. "users/abc123")' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'firestore_write',
+    description: 'Write/merge a Firestore document. Set merge=false to overwrite entirely.',
+    method: 'POST',
+    path: 'admin/firestore',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Firestore document path (e.g. "users/abc123")' },
+        document: { type: 'object', description: 'Document data to write' },
+        merge: { type: 'boolean', description: 'Merge with existing document (default: true)', default: true },
+      },
+      required: ['path', 'document'],
+    },
+  },
+  {
+    name: 'firestore_query',
+    description: 'Query a Firestore collection with where clauses, ordering, and limits. Each query in the array has: collection (string), where (array of {field, operator, value}), orderBy (array of {field, order}), limit (number).',
+    method: 'POST',
+    path: 'admin/firestore/query',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        queries: {
+          type: 'array',
+          description: 'Array of query objects',
+          items: {
+            type: 'object',
+            properties: {
+              collection: { type: 'string', description: 'Collection path (e.g. "users")' },
+              where: {
+                type: 'array',
+                description: 'Where clauses',
+                items: {
+                  type: 'object',
+                  properties: {
+                    field: { type: 'string' },
+                    operator: { type: 'string', description: 'Firestore operator: ==, !=, <, <=, >, >=, in, not-in, array-contains, array-contains-any' },
+                    value: { description: 'Value to compare against' },
+                  },
+                  required: ['field', 'operator', 'value'],
+                },
+              },
+              orderBy: {
+                type: 'array',
+                description: 'Order by clauses',
+                items: {
+                  type: 'object',
+                  properties: {
+                    field: { type: 'string' },
+                    order: { type: 'string', enum: ['asc', 'desc'], default: 'asc' },
+                  },
+                  required: ['field'],
+                },
+              },
+              limit: { type: 'number', description: 'Max documents to return' },
+            },
+            required: ['collection'],
+          },
+        },
+      },
+      required: ['queries'],
+    },
+  },
+
+  // --- Email ---
+  {
+    name: 'send_email',
+    description: 'Send a transactional email via SendGrid. Recipients can be email strings, UIDs (auto-resolves from Firestore), or {email, name} objects.',
+    method: 'POST',
+    path: 'admin/email',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        to: { description: 'Recipient(s): email string, UID string, {email, name} object, or array of any' },
+        cc: { description: 'CC recipient(s): same formats as "to"' },
+        bcc: { description: 'BCC recipient(s): same formats as "to"' },
+        subject: { type: 'string', description: 'Email subject line' },
+        template: { type: 'string', description: 'SendGrid template ID or name' },
+        html: { type: 'string', description: 'Raw HTML body (alternative to template)' },
+        data: { type: 'object', description: 'Template variables / dynamic data' },
+        sender: { type: 'string', description: 'Sender preset name (e.g. "marketing", "support")' },
+        group: { description: 'Unsubscribe group ID (number or string)' },
+        categories: { type: 'array', items: { type: 'string' }, description: 'Email categories for tracking' },
+      },
+      required: ['to'],
+    },
+  },
+
+  // --- Notifications ---
+  {
+    name: 'send_notification',
+    description: 'Send a push notification via FCM to users or topics',
+    method: 'POST',
+    path: 'admin/notification',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        notification: {
+          type: 'object',
+          description: 'Notification content',
+          properties: {
+            title: { type: 'string', description: 'Notification title' },
+            body: { type: 'string', description: 'Notification body text' },
+          },
+          required: ['title', 'body'],
+        },
+        filters: {
+          type: 'object',
+          description: 'Targeting filters',
+          properties: {
+            tags: { description: 'Filter by tags' },
+            owner: { type: 'string', description: 'Target specific user UID' },
+            token: { type: 'string', description: 'Target specific FCM token' },
+            limit: { type: 'number', description: 'Max recipients' },
+          },
+        },
+      },
+      required: ['notification'],
+    },
+  },
+
+  // --- User Management ---
+  {
+    name: 'get_user',
+    description: 'Get the currently authenticated user info. To look up a specific user, use firestore_read with path "users/{uid}" instead.',
+    method: 'GET',
+    path: 'user',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'get_subscription',
+    description: 'Get subscription info for a user. Defaults to the authenticated user, or pass a uid to look up another user (admin only).',
+    method: 'GET',
+    path: 'user/subscription',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        uid: { type: 'string', description: 'User UID to look up (admin only, defaults to authenticated user)' },
+      },
+    },
+  },
+  {
+    name: 'sync_users',
+    description: 'Sync user data across systems (marketing contacts, etc). Processes users in batches.',
+    method: 'POST',
+    path: 'admin/users/sync',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+
+  // --- Marketing Campaigns ---
+  {
+    name: 'list_campaigns',
+    description: 'List marketing campaigns with optional filters by date range, status, and type',
+    method: 'GET',
+    path: 'marketing/campaign',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Get a specific campaign by ID' },
+        start: { description: 'Start date filter (ISO string or unix timestamp)' },
+        end: { description: 'End date filter (ISO string or unix timestamp)' },
+        status: { type: 'string', description: 'Filter by status: pending, sent, failed' },
+        type: { type: 'string', description: 'Filter by type: email, push' },
+        limit: { type: 'number', description: 'Max results (default: 100)' },
+      },
+    },
+  },
+  {
+    name: 'create_campaign',
+    description: 'Create a marketing campaign (email or push notification). Can be immediate or scheduled.',
+    method: 'POST',
+    path: 'marketing/campaign',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Campaign name' },
+        subject: { type: 'string', description: 'Email subject line' },
+        type: { type: 'string', enum: ['email', 'push'], default: 'email', description: 'Campaign type' },
+        preheader: { type: 'string', description: 'Email preheader text' },
+        content: { type: 'string', description: 'Campaign content (markdown)' },
+        template: { type: 'string', description: 'Email template name', default: 'default' },
+        segments: { type: 'array', items: { type: 'string' }, description: 'Target segment keys (e.g. ["subscription_free"])' },
+        excludeSegments: { type: 'array', items: { type: 'string' }, description: 'Exclude segment keys' },
+        all: { type: 'boolean', description: 'Send to all contacts (overrides segments)' },
+        sendAt: { description: 'Schedule time (ISO string or unix timestamp). Omit for immediate.' },
+        sender: { type: 'string', description: 'Sender preset name', default: 'marketing' },
+        test: { type: 'boolean', description: 'Send as test (to sender only)', default: false },
+        data: { type: 'object', description: 'Template variables' },
+      },
+      required: ['name', 'subject'],
+    },
+  },
+
+  // --- Stats ---
+  {
+    name: 'get_stats',
+    description: 'Get system statistics (user counts, subscription metrics, etc.)',
+    method: 'GET',
+    path: 'admin/stats',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        update: { description: 'Pass true to force recalculation, or an object for specific stat options' },
+      },
+    },
+  },
+
+  // --- Payments ---
+  {
+    name: 'cancel_subscription',
+    description: 'Cancel a subscription at the end of the current billing period. Requires the authenticated user to have an active subscription.',
+    method: 'POST',
+    path: 'payments/cancel',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        reason: { type: 'string', description: 'Cancellation reason' },
+        feedback: { type: 'string', description: 'Additional feedback' },
+        confirmed: { type: 'boolean', description: 'Must be true to confirm cancellation' },
+      },
+      required: ['confirmed'],
+    },
+  },
+  {
+    name: 'refund_payment',
+    description: 'Process a refund for a subscription. Immediately cancels and refunds the latest payment.',
+    method: 'POST',
+    path: 'payments/refund',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        reason: { type: 'string', description: 'Refund reason (required)' },
+        feedback: { type: 'string', description: 'Additional feedback' },
+        confirmed: { type: 'boolean', description: 'Must be true to confirm refund' },
+      },
+      required: ['reason', 'confirmed'],
+    },
+  },
+
+  // --- Cron ---
+  {
+    name: 'run_cron',
+    description: 'Manually trigger a cron job by ID (e.g. "daily", "reset-usage", "marketing-campaigns")',
+    method: 'POST',
+    path: 'admin/cron',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Cron job ID to trigger' },
+      },
+      required: ['id'],
+    },
+  },
+
+  // --- Blog Posts ---
+  {
+    name: 'create_post',
+    description: 'Create a blog post. Handles image downloading, GitHub upload, and body rewriting.',
+    method: 'POST',
+    path: 'admin/post',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Post title' },
+        body: { type: 'string', description: 'Post body (markdown)' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Post tags' },
+        categories: { type: 'array', items: { type: 'string' }, description: 'Post categories' },
+        headerImageURL: { type: 'string', description: 'Header image URL' },
+        status: { type: 'string', description: 'Post status (e.g. "draft", "published")' },
+      },
+      required: ['title', 'body'],
+    },
+  },
+
+  // --- Backup ---
+  {
+    name: 'create_backup',
+    description: 'Create a Firestore data backup. Optionally filter with a deletion regex.',
+    method: 'POST',
+    path: 'admin/backup',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        deletionRegex: { type: 'string', description: 'Regex pattern to filter documents for deletion (optional)' },
+      },
+    },
+  },
+
+  // --- Hooks ---
+  {
+    name: 'run_hook',
+    description: 'Execute a custom hook by path (e.g. "cron/daily/my-job")',
+    method: 'POST',
+    path: 'admin/hook',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Hook path to execute' },
+      },
+      required: ['path'],
+    },
+  },
+
+  // --- UUID ---
+  {
+    name: 'generate_uuid',
+    description: 'Generate a UUID (v4 random or v5 namespace-based)',
+    method: 'POST',
+    path: 'general/uuid',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name for v5 UUID generation' },
+        input: { type: 'string', description: 'Input string for v5 UUID' },
+        version: { description: 'UUID version (default: "5")', default: '5' },
+        namespace: { type: 'string', description: 'UUID namespace' },
+      },
+    },
+  },
+
+  // --- Health Check ---
+  {
+    name: 'health_check',
+    description: 'Check if the BEM server is running and responding',
+    method: 'GET',
+    path: 'test/health',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+];