backend-manager 5.6.4 → 5.7.1

package/src/mcp/index.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 
 /**
- * BEM MCP Server
+ * BEM MCP Server (Stdio Transport)
  *
  * 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
+ *   npx bm mcp                       # admin (uses BACKEND_MANAGER_KEY)
+ *   npx bm mcp --token <api-key>     # user-level (uses API key)
+ *   npx bm mcp                       # public-only (no key, no token)
  *
  * Environment variables:
  *   BEM_URL              - BEM server URL (default: http://localhost:5002)
@@ -17,7 +19,8 @@ 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 builtinTools = require('./tools.js');
+const { resolveAuthInfo, filterToolsByRole, loadConsumerTools, buildToolMap } = require('./utils.js');
 const packageJSON = require('../../package.json');
 
 /**
@@ -25,6 +28,8 @@ const packageJSON = require('../../package.json');
  * @param {object} options
  * @param {string} options.baseUrl - BEM server URL
  * @param {string} options.backendManagerKey - Admin API key
+ * @param {string} options.userToken - User API key (for user-level connections)
+ * @param {string} options.cwd - Consumer project functions directory (for consumer tool discovery)
  */
 async function startServer(options) {
   options = options || {};
@@ -35,12 +40,30 @@ async function startServer(options) {
   const backendManagerKey = options.backendManagerKey
     || process.env.BACKEND_MANAGER_KEY
     || '';
+  const userToken = options.userToken || '';
 
-  if (!backendManagerKey) {
-    console.error('[BEM MCP] Warning: No BACKEND_MANAGER_KEY set. Admin routes will fail.');
+  // Determine auth role
+  const token = backendManagerKey || userToken || '';
+  const authInfo = resolveAuthInfo(token);
+
+  if (authInfo.role === 'public') {
+    console.error('[BEM MCP] No key or token set. Only public tools will be available.');
   }
 
-  const client = new BEMClient({ baseUrl, backendManagerKey });
+  // Build client with appropriate auth
+  const client = new BEMClient({
+    baseUrl,
+    backendManagerKey: authInfo.role === 'admin' ? token : '',
+    userToken: authInfo.role === 'user' ? token : '',
+  });
+
+  // Load and merge consumer tools (consumer overrides win)
+  const consumerTools = loadConsumerTools(options.cwd);
+  const toolMap = buildToolMap(builtinTools, consumerTools);
+  const allTools = Array.from(toolMap.values());
+
+  // Filter by role
+  const visibleTools = filterToolsByRole(allTools, authInfo.role);
 
   // Create the MCP server
   const server = new Server(
@@ -55,19 +78,15 @@ async function startServer(options) {
     },
   );
 
-  // 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
+  // Handle tools/list — return role-filtered tool definitions
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
-      tools: tools.map((tool) => ({
+      tools: visibleTools.map((tool) => ({
         name: tool.name,
         description: tool.description,
         inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+        annotations: tool.annotations,
       })),
     };
   });
@@ -75,19 +94,26 @@ async function startServer(options) {
   // Handle tools/call — execute the requested tool
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
-    const tool = toolMap[name];
+    const tool = toolMap.get(name);
 
-    if (!tool) {
+    if (!tool || !visibleTools.some((t) => t.name === name)) {
       return {
         content: [{ type: 'text', text: `Unknown tool: ${name}` }],
         isError: true,
       };
     }
 
+    // Handler-based consumer tools require HTTP transport
+    if (tool.handler && !tool.path) {
+      return {
+        content: [{ type: 'text', text: `Tool "${name}" requires HTTP transport (handler-based tools cannot run over stdio).` }],
+        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);
@@ -113,7 +139,11 @@ async function startServer(options) {
 
   // 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`);
+  console.error(`[BEM MCP] Role: ${authInfo.role} | ${visibleTools.length}/${allTools.length} tools available`);
+
+  if (consumerTools.length > 0) {
+    console.error(`[BEM MCP] ${consumerTools.length} consumer tool(s) loaded`);
+  }
 }
 
 // Allow direct execution or require

package/src/mcp/tools.js

@@ -2,14 +2,17 @@
  * MCP Tool Definitions
  *
  * Each tool maps to a BEM route with method, path, and JSON Schema for inputs.
+ * annotations.readOnlyHint / destructiveHint control Claude Desktop's read/write categorization.
  */
 module.exports = [
   // --- Firestore ---
   {
     name: 'firestore_read',
     description: 'Read a Firestore document by path (e.g. "users/abc123")',
+    role: 'admin',
     method: 'GET',
     path: 'admin/firestore',
+    annotations: { title: 'Read a Firestore document', readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -21,8 +24,10 @@ module.exports = [
   {
     name: 'firestore_write',
     description: 'Write/merge a Firestore document. Set merge=false to overwrite entirely.',
+    role: 'admin',
     method: 'POST',
     path: 'admin/firestore',
+    annotations: { title: 'Write a Firestore document', readOnlyHint: false, destructiveHint: false, idempotentHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -36,8 +41,10 @@ module.exports = [
   {
     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).',
+    role: 'admin',
     method: 'POST',
     path: 'admin/firestore/query',
+    annotations: { title: 'Query a Firestore collection', readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -87,8 +94,10 @@ module.exports = [
   {
     name: 'send_email',
     description: 'Send a transactional email via SendGrid. Recipients can be email strings, UIDs (auto-resolves from Firestore), or {email, name} objects.',
+    role: 'admin',
     method: 'POST',
     path: 'admin/email',
+    annotations: { title: 'Send a transactional email', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -111,8 +120,10 @@ module.exports = [
   {
     name: 'send_notification',
     description: 'Send a push notification via FCM to users or topics',
+    role: 'admin',
     method: 'POST',
     path: 'admin/notification',
+    annotations: { title: 'Send a push notification', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -144,8 +155,10 @@ module.exports = [
   {
     name: 'get_user',
     description: 'Get the currently authenticated user info. To look up a specific user, use firestore_read with path "users/{uid}" instead.',
+    role: 'user',
     method: 'GET',
     path: 'user',
+    annotations: { title: 'Get authenticated user info', readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: {},
@@ -154,8 +167,10 @@ module.exports = [
   {
     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).',
+    role: 'user',
     method: 'GET',
     path: 'user/subscription',
+    annotations: { title: 'Get subscription info', readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -166,8 +181,10 @@ module.exports = [
   {
     name: 'sync_users',
     description: 'Sync user data across systems (marketing contacts, etc). Processes users in batches.',
+    role: 'admin',
     method: 'POST',
     path: 'admin/users/sync',
+    annotations: { title: 'Sync users across systems', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     inputSchema: {
       type: 'object',
       properties: {},
@@ -178,8 +195,10 @@ module.exports = [
   {
     name: 'list_campaigns',
     description: 'List marketing campaigns with optional filters by date range, status, and type',
+    role: 'admin',
     method: 'GET',
     path: 'marketing/campaign',
+    annotations: { title: 'List marketing campaigns', readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -195,8 +214,10 @@ module.exports = [
   {
     name: 'create_campaign',
     description: 'Create a marketing campaign (email or push notification). Can be immediate or scheduled.',
+    role: 'admin',
     method: 'POST',
     path: 'marketing/campaign',
+    annotations: { title: 'Create a marketing campaign', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -217,12 +238,92 @@ module.exports = [
     },
   },
 
+  {
+    name: 'update_campaign',
+    description: 'Update a pending marketing campaign. Only pending campaigns can be edited.',
+    role: 'admin',
+    method: 'PUT',
+    path: 'marketing/campaign',
+    annotations: { title: 'Update a campaign', readOnlyHint: false, destructiveHint: false },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Campaign ID to update' },
+        name: { type: 'string', description: 'Campaign name' },
+        subject: { type: 'string', description: 'Email subject line' },
+        preheader: { type: 'string', description: 'Email preheader text' },
+        template: { type: 'string', description: 'Email template name' },
+        data: { type: 'object', description: 'Template data' },
+        segments: { type: 'array', items: { type: 'string' }, description: 'Target segment keys' },
+        excludeSegments: { type: 'array', items: { type: 'string' }, description: 'Exclude segment keys' },
+        all: { type: 'boolean', description: 'Send to all contacts' },
+        sendAt: { description: 'Reschedule time (ISO string or unix timestamp)' },
+        sender: { type: 'string', description: 'Sender preset name' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'delete_campaign',
+    description: 'Delete a pending marketing campaign. Only pending campaigns can be deleted.',
+    role: 'admin',
+    method: 'DELETE',
+    path: 'marketing/campaign',
+    annotations: { title: 'Delete a campaign', readOnlyHint: false, destructiveHint: true },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Campaign ID to delete' },
+      },
+      required: ['id'],
+    },
+  },
+
+  // --- Marketing Contacts ---
+  {
+    name: 'create_contact',
+    description: 'Add a marketing contact to email providers (SendGrid/Beehiiv). Admin mode skips reCAPTCHA and allows tags.',
+    role: 'admin',
+    method: 'POST',
+    path: 'marketing/contact',
+    annotations: { title: 'Add a marketing contact', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        email: { type: 'string', description: 'Contact email address' },
+        firstName: { type: 'string', description: 'First name' },
+        lastName: { type: 'string', description: 'Last name' },
+        source: { type: 'string', description: 'Contact source (e.g. "manual", "import")' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Contact tags' },
+        skipValidation: { type: 'boolean', description: 'Skip email validation (admin only)', default: false },
+      },
+      required: ['email'],
+    },
+  },
+  {
+    name: 'delete_contact',
+    description: 'Remove a marketing contact from email providers and revoke marketing consent.',
+    role: 'admin',
+    method: 'DELETE',
+    path: 'marketing/contact',
+    annotations: { title: 'Remove a marketing contact', readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        email: { type: 'string', description: 'Contact email to remove' },
+      },
+      required: ['email'],
+    },
+  },
+
   // --- Stats ---
   {
     name: 'get_stats',
     description: 'Get system statistics (user counts, subscription metrics, etc.)',
+    role: 'admin',
     method: 'GET',
     path: 'admin/stats',
+    annotations: { title: 'Get system statistics', readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -235,8 +336,10 @@ module.exports = [
   {
     name: 'cancel_subscription',
     description: 'Cancel a subscription at the end of the current billing period. Requires the authenticated user to have an active subscription.',
+    role: 'admin',
     method: 'POST',
     path: 'payments/cancel',
+    annotations: { title: 'Cancel a subscription', readOnlyHint: false, destructiveHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -250,8 +353,10 @@ module.exports = [
   {
     name: 'refund_payment',
     description: 'Process a refund for a subscription. Immediately cancels and refunds the latest payment.',
+    role: 'admin',
     method: 'POST',
     path: 'payments/refund',
+    annotations: { title: 'Refund a payment', readOnlyHint: false, destructiveHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -263,12 +368,29 @@ module.exports = [
     },
   },
 
+  {
+    name: 'get_payment_portal',
+    description: 'Generate a Stripe Billing Portal link for the authenticated user to manage their subscription.',
+    role: 'admin',
+    method: 'POST',
+    path: 'payments/portal',
+    annotations: { title: 'Get payment portal link', readOnlyHint: true, openWorldHint: true },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        returnUrl: { type: 'string', description: 'URL to redirect to after the portal session' },
+      },
+    },
+  },
+
   // --- Cron ---
   {
     name: 'run_cron',
     description: 'Manually trigger a cron job by ID (e.g. "daily", "reset-usage", "marketing-campaigns")',
+    role: 'admin',
     method: 'POST',
     path: 'admin/cron',
+    annotations: { title: 'Trigger a cron job', readOnlyHint: false, destructiveHint: false },
     inputSchema: {
       type: 'object',
       properties: {
@@ -282,8 +404,10 @@ module.exports = [
   {
     name: 'create_post',
     description: 'Create a blog post. Handles image downloading, GitHub upload, and body rewriting.',
+    role: 'admin',
     method: 'POST',
     path: 'admin/post',
+    annotations: { title: 'Create a blog post', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -297,13 +421,33 @@ module.exports = [
       required: ['title', 'body'],
     },
   },
+  {
+    name: 'update_post',
+    description: 'Update an existing blog post. Fetches the post by URL and uploads changes via GitHub.',
+    role: 'admin',
+    method: 'PUT',
+    path: 'admin/post',
+    annotations: { title: 'Update a blog post', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'Blog post URL to update' },
+        body: { type: 'string', description: 'Updated post content body' },
+        title: { type: 'string', description: 'Updated post title' },
+        postPath: { type: 'string', description: 'Path to the post (default: "guest")' },
+      },
+      required: ['url', 'body'],
+    },
+  },
 
   // --- Backup ---
   {
     name: 'create_backup',
     description: 'Create a Firestore data backup. Optionally filter with a deletion regex.',
+    role: 'admin',
     method: 'POST',
     path: 'admin/backup',
+    annotations: { title: 'Create a Firestore backup', readOnlyHint: false, destructiveHint: false },
     inputSchema: {
       type: 'object',
       properties: {
@@ -316,8 +460,10 @@ module.exports = [
   {
     name: 'run_hook',
     description: 'Execute a custom hook by path (e.g. "cron/daily/my-job")',
+    role: 'admin',
     method: 'POST',
     path: 'admin/hook',
+    annotations: { title: 'Run a custom hook', readOnlyHint: false, destructiveHint: false },
     inputSchema: {
       type: 'object',
       properties: {
@@ -331,8 +477,10 @@ module.exports = [
   {
     name: 'generate_uuid',
     description: 'Generate a UUID (v4 random or v5 namespace-based)',
+    role: 'admin',
     method: 'POST',
     path: 'general/uuid',
+    annotations: { title: 'Generate a UUID', readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: {
@@ -348,8 +496,10 @@ module.exports = [
   {
     name: 'health_check',
     description: 'Check if the BEM server is running and responding',
+    role: 'public',
     method: 'GET',
     path: 'test/health',
+    annotations: { title: 'Check server health', readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: {},

package/src/mcp/utils.js

@@ -0,0 +1,108 @@
+const path = require('path');
+
+const ROLE_HIERARCHY = {
+  admin: ['admin', 'user', 'public'],
+  user: ['user', 'public'],
+  public: ['public'],
+};
+
+/**
+ * Classify a Bearer token into a role without hitting the database.
+ * Actual validation happens at the route level when a tool is called.
+ */
+function resolveAuthInfo(token) {
+  const configKey = process.env.BACKEND_MANAGER_KEY || '';
+
+  if (token && configKey && token === configKey) {
+    return { role: 'admin', authType: 'adminKey', token };
+  }
+
+  if (token) {
+    return { role: 'user', authType: 'userToken', token };
+  }
+
+  return { role: 'public', authType: 'none', token: '' };
+}
+
+/**
+ * Filter tools to only those visible for a given role.
+ * admin → all, user → user + public, public → public only.
+ */
+function filterToolsByRole(tools, role) {
+  const allowed = ROLE_HIERARCHY[role] || ROLE_HIERARCHY.public;
+
+  return tools.filter((tool) => allowed.includes(tool.role || 'admin'));
+}
+
+/**
+ * Load consumer MCP tools from `functions/mcp.js` if it exists.
+ * Returns an empty array if the file doesn't exist or fails to load.
+ */
+function loadConsumerTools(cwd) {
+  if (!cwd) {
+    return [];
+  }
+
+  const mcpPath = path.join(cwd, 'mcp.js');
+
+  try {
+    const jetpack = require('fs-jetpack');
+
+    if (!jetpack.exists(mcpPath)) {
+      return [];
+    }
+
+    const consumerTools = require(mcpPath);
+
+    if (!Array.isArray(consumerTools)) {
+      console.error(`[BEM MCP] Consumer mcp.js must export an array, got ${typeof consumerTools}`);
+      return [];
+    }
+
+    for (const tool of consumerTools) {
+      if (!tool.name || !tool.description) {
+        console.error(`[BEM MCP] Consumer tool missing name or description:`, tool);
+        return [];
+      }
+
+      if (!tool.path && !tool.handler) {
+        console.error(`[BEM MCP] Consumer tool "${tool.name}" must have a path or handler`);
+        return [];
+      }
+
+      tool.role = tool.role || 'admin';
+      tool._consumer = true;
+    }
+
+    return consumerTools;
+  } catch (error) {
+    console.error(`[BEM MCP] Failed to load consumer tools from ${mcpPath}:`, error.message);
+    return [];
+  }
+}
+
+/**
+ * Merge built-in and consumer tools into a Map.
+ * Consumer tools with the same name override built-ins.
+ */
+function buildToolMap(builtinTools, consumerTools) {
+  const map = new Map();
+
+  for (const tool of builtinTools) {
+    map.set(tool.name, tool);
+  }
+
+  for (const tool of consumerTools) {
+    map.set(tool.name, tool);
+  }
+
+  return map;
+}
+
+module.exports = {
+  resolveAuthInfo,
+  filterToolsByRole,
+  loadConsumerTools,
+  buildToolMap,
+  ROLE_HIERARCHY,
+};

package/src/test/fixtures/firebase-project/firebase.json

@@ -8,7 +8,7 @@
     ],
     "rewrites": [
       {
-        "source": "{/backend-manager,/backend-manager/**}",
+        "source": "{/backend-manager,/backend-manager/**,/mcp,/mcp/**,/.well-known/oauth-protected-resource,/.well-known/oauth-authorization-server,/authorize,/token,/register}",
         "function": "bm_api"
       }
     ]