@littlebearapps/outlook-assistant 3.13.0 → 3.14.1

package/rules/index.js

@@ -7,6 +7,8 @@ const handleUpdateRule = require('./update');
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { checkRateLimit } = require('../utils/safety');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Delete rule handler
@@ -16,19 +18,8 @@ const { checkRateLimit } = require('../utils/safety');
 async function handleDeleteRule(args) {
   const { ruleName, ruleId } = args;
 
-  // Rate limit
-  const rateLimitError = checkRateLimit('manage-rules');
-  if (rateLimitError) return rateLimitError;
-
   if (!ruleName && !ruleId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Either ruleName or ruleId is required.',
-        },
-      ],
-    };
+    return toolError('Either ruleName or ruleId is required.');
   }
 
   try {
@@ -42,19 +33,17 @@ async function handleDeleteRule(args) {
       const rules = await getInboxRules(accessToken);
       const rule = rules.find((r) => r.displayName === ruleName);
       if (!rule) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Rule with name "${ruleName}" not found.`,
-            },
-          ],
-        };
+        return toolError(`Rule with name "${ruleName}" not found.`);
       }
       resolvedId = rule.id;
       displayName = ruleName;
     }
 
+    // Checked only once there is a rule to delete, so a bad call doesn't
+    // use up a slot (#279)
+    const rateLimitError = checkRateLimit('manage-rules');
+    if (rateLimitError) return rateLimitError;
+
     await callGraphAPI(
       accessToken,
       'DELETE',
@@ -71,23 +60,9 @@ async function handleDeleteRule(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error deleting rule: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error deleting rule: ${error.message}`);
   }
 }
 
@@ -100,25 +75,15 @@ async function handleEditRuleSequence(args) {
   const { ruleName, sequence } = args;
 
   if (!ruleName) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Rule name is required. Please specify the exact name of an existing rule.',
-        },
-      ],
-    };
+    return toolError(
+      'Rule name is required. Please specify the exact name of an existing rule.'
+    );
   }
 
   if (!sequence || isNaN(sequence) || sequence < 1) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'A positive sequence number is required. Lower numbers run first (higher priority).',
-        },
-      ],
-    };
+    return toolError(
+      'A positive sequence number is required. Lower numbers run first (higher priority).'
+    );
   }
 
   try {
@@ -127,16 +92,13 @@ async function handleEditRuleSequence(args) {
 
     const rule = rules.find((r) => r.displayName === ruleName);
     if (!rule) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Rule with name "${ruleName}" not found.`,
-          },
-        ],
-      };
+      return toolError(`Rule with name "${ruleName}" not found.`);
     }
 
+    // Reordering is a write, so it shares the manage-rules limit (#273)
+    const rateLimitError = checkRateLimit('manage-rules');
+    if (rateLimitError) return rateLimitError;
+
     await callGraphAPI(
       accessToken,
       'PATCH',
@@ -144,34 +106,41 @@ async function handleEditRuleSequence(args) {
       { sequence }
     );
 
+    // Exchange may renumber other rules to make room, and deleting a rule
+    // later doesn't shift them back (#307), so show the resulting order.
+    let order = '';
+    try {
+      const after = await getInboxRules(accessToken);
+      const before = new Map(rules.map((r) => [r.id, r.sequence]));
+      const lines = [...after]
+        .sort((a, b) => (a.sequence ?? 0) - (b.sequence ?? 0))
+        .map((r) => `${r.sequence}: ${r.displayName}`);
+      const moved = after.filter(
+        (r) => r.id !== rule.id && before.get(r.id) !== r.sequence
+      );
+      const movedNote =
+        moved.length > 0
+          ? `\n\nRenumbered by Exchange: ${moved.map((r) => `"${r.displayName}" ${before.get(r.id)} → ${r.sequence}`).join('; ')}. Tell the user; deleting a rule later doesn't shift them back.`
+          : '\n\nNo other rule was renumbered.';
+      order = `\n\nRule order now (sequence: name):\n${lines.join('\n')}${movedNote}`;
+    } catch (_error) {
+      // The reorder succeeded; the order listing is a courtesy.
+    }
+
     return {
       content: [
         {
           type: 'text',
-          text: `Successfully updated the sequence of rule "${ruleName}" to ${sequence}.`,
+          text: `Successfully updated the sequence of rule "${ruleName}" to ${sequence}.${order}`,
         },
       ],
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error updating rule sequence: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error updating rule sequence: ${error.message}`);
   }
 }
 
@@ -180,13 +149,8 @@ const rulesTools = [
   {
     name: 'manage-rules',
     description:
-      'Server-side inbox rule CRUD (destructive: covers `delete`; supports `dryRun` on create/update for preview). Rules run on the Exchange server regardless of which client is open. action=`list` (default) returns rules with id/name/sequence — pass `includeDetails: true` to expand conditions/actions/exceptions. action=`create` builds a new rule from condition params (12 supported: fromAddresses, containsSubject, bodyContains, hasAttachments, importance, sentTo, sensitivity, etc.), action params (9 supported: moveToFolder/copyToFolder — folder name, nested path like `Triage/Delete`, or ID — forwardTo, redirectTo, assignCategories, markAsRead, delete, etc.), and optional `except*` exceptions. action=`update` patches the named fields by `ruleId`. action=`reorder` changes execution priority via `sequence` (lower = earlier). action=`delete` removes a rule. Recipient allowlist applies to forwardTo/redirectTo. `permanentDelete` action is intentionally omitted (too dangerous for AI use — use the Outlook UI). Subject to session rate limits (`OUTLOOK_MAX_MANAGE_RULES_PER_SESSION`).',
-    annotations: {
-      title: 'Inbox Rules',
-      readOnlyHint: false,
-      destructiveHint: true,
-      openWorldHint: false,
-    },
+      'Server-side inbox rules (destructive: covers `delete`; `dryRun` previews create/update). Rules run on the Exchange server whichever client is open. action=`list` (default) returns rules with id/name/sequence; `includeDetails: true` adds conditions/actions/exceptions. action=`create` builds a rule from condition params (12, e.g. fromAddresses, containsSubject, bodyContains, hasAttachments, importance, sensitivity), action params (9, e.g. moveToFolder/copyToFolder — folder name, nested path like `Triage/Delete`, or ID — forwardTo, redirectTo, assignCategories, markAsRead, delete) and optional `except*` exceptions. action=`update` patches fields by `ruleId` or `ruleName`. action=`reorder` changes priority via `sequence` (lower runs first). action=`delete` removes a rule. The recipient allowlist applies to forwardTo/redirectTo. There is no `permanentDelete` action. Changes count against the session limit (`OUTLOOK_MAX_MANAGE_RULES_PER_SESSION`, else `OUTLOOK_MAX_EMAILS_PER_SESSION`); 0 refuses them.',
+    ...toolMetadata('manage-rules', 'Inbox Rules'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -217,7 +181,7 @@ const rulesTools = [
         dryRun: {
           type: 'boolean',
           description:
-            'Preview rule without creating/updating (action=create, action=update)',
+            'Preview only (action=create or update): shows the rule without creating or changing it. Other actions refuse dryRun and change nothing. Default false.',
         },
         isEnabled: {
           type: 'boolean',
@@ -404,14 +368,9 @@ const rulesTools = [
         case 'list':
           return handleListRules(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: list, create, update, reorder, delete.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: list, create, update, reorder, delete.`
+          );
       }
     },
   },

package/rules/list.js

@@ -3,6 +3,8 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * List rules handler
@@ -27,24 +29,10 @@ async function handleListRules(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error listing rules: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error listing rules: ${error.message}`);
   }
 }
 
@@ -64,7 +52,7 @@ async function getInboxRules(accessToken) {
 
     return response.value || [];
   } catch (error) {
-    console.error(`Error getting inbox rules: ${error.message}`);
+    log.debug(`Error getting inbox rules: ${error.message}`);
     throw error;
   }
 }
@@ -165,7 +153,7 @@ function formatRuleConditions(rule) {
   }
 
   // Booleans
-  if (c.hasAttachment === true) conditions.push('Has attachment');
+  if (c.hasAttachments === true) conditions.push('Has attachment');
   if (c.sentToMe === true) conditions.push('Sent to me');
   if (c.sentOnlyToMe === true) conditions.push('Sent only to me');
   if (c.sentCcMe === true) conditions.push('I am in CC');
@@ -281,7 +269,7 @@ function formatRuleExceptions(rule) {
   if (e.recipientContains?.length > 0) {
     parts.push(`Recipient contains: "${e.recipientContains.join('", "')}"`);
   }
-  if (e.hasAttachment === true) parts.push('Has attachment');
+  if (e.hasAttachments === true) parts.push('Has attachment');
   if (e.importance) parts.push(`Importance: ${e.importance}`);
   if (e.sensitivity) parts.push(`Sensitivity: ${e.sensitivity}`);
   if (e.sentToMe === true) parts.push('Sent to me');

package/rules/rule-builder.js

@@ -4,6 +4,7 @@
  */
 const { resolveFolder, looksLikeFolderId } = require('../folder/resolve');
 const { checkRecipientAllowlist } = require('../utils/safety');
+const { toolError } = require('../utils/tool-error');
 
 const VALID_IMPORTANCE = ['low', 'normal', 'high'];
 const VALID_SENSITIVITY = ['normal', 'personal', 'private', 'confidential'];
@@ -75,7 +76,7 @@ function buildConditions(args) {
   }
 
   // Boolean conditions
-  if (args.hasAttachments === true) conditions.hasAttachment = true;
+  if (args.hasAttachments === true) conditions.hasAttachments = true;
   if (args.sentToMe === true) conditions.sentToMe = true;
   if (args.sentOnlyToMe === true) conditions.sentOnlyToMe = true;
   if (args.sentCcMe === true) conditions.sentCcMe = true;
@@ -197,38 +198,35 @@ async function buildActions(args, accessToken) {
     }
   }
 
-  // Recipient-based actions (comma-separated emails → recipient objects)
+  // Recipient-based actions (comma-separated emails → recipient objects).
+  // create/update refuse blocked recipients up front (checkRuleRecipients);
+  // this is the backstop, so a blocked forward is never silently dropped.
   if (args.forwardTo) {
     const recipients = formatRecipientObjects(args.forwardTo);
     if (recipients.length > 0) {
-      // Check allowlist if configured
-      const allowlistError = checkRecipientAllowlist(recipients);
-      if (allowlistError) {
-        warnings.push(
-          `Forward recipients blocked by allowlist: ${args.forwardTo}`
-        );
-      } else {
-        actions.forwardTo = recipients;
-        warnings.push(
-          `This rule will forward all matching emails to: ${args.forwardTo}. Verify these addresses are correct.`
+      if (checkRecipientAllowlist(recipients)) {
+        throw new Error(
+          `forwardTo recipients blocked by OUTLOOK_ALLOWED_RECIPIENTS: ${args.forwardTo}`
         );
       }
+      actions.forwardTo = recipients;
+      warnings.push(
+        `This rule will forward all matching emails to: ${args.forwardTo}. Verify these addresses are correct.`
+      );
     }
   }
   if (args.redirectTo) {
     const recipients = formatRecipientObjects(args.redirectTo);
     if (recipients.length > 0) {
-      const allowlistError = checkRecipientAllowlist(recipients);
-      if (allowlistError) {
-        warnings.push(
-          `Redirect recipients blocked by allowlist: ${args.redirectTo}`
-        );
-      } else {
-        actions.redirectTo = recipients;
-        warnings.push(
-          `This rule will redirect all matching emails to: ${args.redirectTo}. The original sender will appear as the sender.`
+      if (checkRecipientAllowlist(recipients)) {
+        throw new Error(
+          `redirectTo recipients blocked by OUTLOOK_ALLOWED_RECIPIENTS: ${args.redirectTo}`
         );
       }
+      actions.redirectTo = recipients;
+      warnings.push(
+        `This rule will redirect all matching emails to: ${args.redirectTo}. The original sender will appear as the sender.`
+      );
     }
   }
 
@@ -240,6 +238,44 @@ async function buildActions(args, accessToken) {
   return { actions, warnings };
 }
 
+/** Rule actions that send matching mail to other people. */
+const RECIPIENT_ACTIONS = ['forwardTo', 'redirectTo'];
+
+/**
+ * Refuse a rule whose forwardTo/redirectTo includes an address that
+ * OUTLOOK_ALLOWED_RECIPIENTS blocks. The whole rule (or update) is refused,
+ * never saved with the blocked forwarding dropped, and a dry run reports the
+ * refusal too. Needs no Graph call, so it runs before sign-in. (#273)
+ * @param {object} args - Tool arguments
+ * @param {{operation?: 'create'|'update', dryRun?: boolean}} [options]
+ * @returns {object|null} - toolError naming the blocked addresses, or null
+ */
+function checkRuleRecipients(args, { operation = 'create', dryRun } = {}) {
+  const blocked = [];
+  for (const param of RECIPIENT_ACTIONS) {
+    const addresses = formatRecipientObjects(args[param])
+      .filter((recipient) => checkRecipientAllowlist([recipient]))
+      .map((recipient) => recipient.emailAddress.address);
+    if (addresses.length > 0) {
+      blocked.push(`${param}: ${addresses.join(', ')}`);
+    }
+  }
+  if (blocked.length === 0) return null;
+
+  const subject = operation === 'update' ? 'Rule update' : 'Rule';
+  const lead = dryRun
+    ? `DRY RUN — ${subject.toLowerCase()} would be refused`
+    : `${subject} refused`;
+  const outcome = operation === 'update' ? 'changed' : 'created';
+  return toolError(
+    `${lead}: OUTLOOK_ALLOWED_RECIPIENTS does not allow ${blocked.join('; ')}. Nothing was ${outcome}; a rule is refused whole rather than saved without the blocked forwarding.`,
+    {
+      nextStep:
+        'Remove the blocked addresses from forwardTo/redirectTo and retry, or ask the user to add them to OUTLOOK_ALLOWED_RECIPIENTS in the server configuration and restart the server.',
+    }
+  );
+}
+
 /**
  * Build a Graph API exceptions object from except* prefixed parameters.
  * @param {object} args - Tool arguments
@@ -267,7 +303,7 @@ function buildExceptions(args) {
     exceptions.bodyContains = parseCommaSeparated(args.exceptBodyContains);
   }
   if (args.exceptHasAttachments === true) {
-    exceptions.hasAttachment = true;
+    exceptions.hasAttachments = true;
   }
 
   return { exceptions, warnings };
@@ -324,6 +360,7 @@ module.exports = {
   buildConditions,
   buildActions,
   buildExceptions,
+  checkRuleRecipients,
   hasAnyCondition,
   hasAnyAction,
 };

package/rules/update.js

@@ -9,7 +9,9 @@ const {
   buildConditions,
   buildActions,
   buildExceptions,
+  checkRuleRecipients,
 } = require('./rule-builder');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Update rule handler — modify an existing rule by name or ID.
@@ -20,32 +22,23 @@ const {
 async function handleUpdateRule(args) {
   const { ruleName, ruleId, name, isEnabled, sequence, dryRun } = args;
 
-  // Rate limit
-  const rateLimitError = checkRateLimit('manage-rules');
-  if (rateLimitError) return rateLimitError;
-
   if (!ruleName && !ruleId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Either ruleName or ruleId is required to identify the rule to update.',
-        },
-      ],
-    };
+    return toolError(
+      'Either ruleName or ruleId is required to identify the rule to update.'
+    );
   }
 
   if (sequence !== undefined && (isNaN(sequence) || sequence < 1)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Sequence must be a positive number greater than zero.',
-        },
-      ],
-    };
+    return toolError('Sequence must be a positive number greater than zero.');
   }
 
+  // Refuse the whole update if the allowlist blocks any forwarding (#273)
+  const recipientError = checkRuleRecipients(args, {
+    operation: 'update',
+    dryRun,
+  });
+  if (recipientError) return recipientError;
+
   try {
     const accessToken = await ensureAuthenticated();
 
@@ -63,14 +56,7 @@ async function handleUpdateRule(args) {
     }
 
     if (!currentRule) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Rule "${ruleName || ruleId}" not found.`,
-          },
-        ],
-      };
+      return toolError(`Rule "${ruleName || ruleId}" not found.`);
     }
 
     // Build PATCH payload — only include fields the user provided
@@ -107,14 +93,9 @@ async function handleUpdateRule(args) {
     // Check for fatal folder-not-found
     const folderNotFound = actWarnings.some((w) => w.includes('not found'));
     if (folderNotFound && Object.keys(actions).length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: actWarnings.filter((w) => w.includes('not found')).join('\n'),
-          },
-        ],
-      };
+      return toolError(
+        actWarnings.filter((w) => w.includes('not found')).join('\n')
+      );
     }
 
     // Build exceptions if any except* param was provided
@@ -126,14 +107,9 @@ async function handleUpdateRule(args) {
 
     // Check that something is actually being changed
     if (Object.keys(patch).length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `No changes specified for rule "${currentRule.displayName}". Provide at least one parameter to update (name, isEnabled, sequence, conditions, actions, or exceptions).`,
-          },
-        ],
-      };
+      return toolError(
+        `No changes specified for rule "${currentRule.displayName}". Provide at least one parameter to update (name, isEnabled, sequence, conditions, actions, or exceptions).`
+      );
     }
 
     // Dry-run: show before/after preview
@@ -142,7 +118,7 @@ async function handleUpdateRule(args) {
       const currentPreview = formatRuleDryRunPreview(currentRule);
       const updatedPreview = formatRuleDryRunPreview(updatedRule);
 
-      let text = `DRY RUN — Update preview for "${currentRule.displayName}" (not applied):\n\n`;
+      let text = `Update preview for "${currentRule.displayName}" (not applied):\n\n`;
       text += `CURRENT:\n${currentPreview}\n\n`;
       text += `AFTER UPDATE:\n${updatedPreview}`;
       if (allWarnings.length > 0) {
@@ -153,6 +129,10 @@ async function handleUpdateRule(args) {
       };
     }
 
+    // Rate limit only real writes, so a dry run never uses up a slot (#273)
+    const rateLimitError = checkRateLimit('manage-rules');
+    if (rateLimitError) return rateLimitError;
+
     // Execute PATCH
     await callGraphAPI(
       accessToken,
@@ -197,24 +177,10 @@ async function handleUpdateRule(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error updating rule: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error updating rule: ${error.message}`);
   }
 }
 

package/server.js

@@ -0,0 +1,41 @@
+/**
+ * MCP server factory: builds the SDK Server for the tool registry.
+ *
+ * Kept apart from index.js (CLI flags, startup warnings, stdio transport) so
+ * protocol behaviour can be tested over an in-memory transport.
+ */
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const config = require('./config');
+const { createRequestHandler } = require('./request-handler');
+const { TOOLS } = require('./tools');
+const { serverInstructions } = require('./utils/server-instructions');
+const { blockedTools } = require('./utils/safety');
+
+/**
+ * @param {Array<object>} [tools] - tool definitions (default: the registry)
+ * @returns {Server}
+ */
+function createServer(tools = TOOLS) {
+  const server = new Server(
+    { name: config.SERVER_NAME, version: config.SERVER_VERSION },
+    {
+      // Spec shape: the tool list never changes at runtime. Nothing else
+      // (resources, prompts, logging) is declared, so those methods return
+      // -32601 rather than empty stubs. (#276)
+      capabilities: { tools: { listChanged: false } },
+      // Model-facing safety rules and usage tips, sent in the initialize
+      // result (#271), naming any tool a session limit of 0 blocks (#302).
+      instructions: serverInstructions({
+        readOnly: config.READ_ONLY,
+        blockedTools: blockedTools(),
+      }),
+    }
+  );
+
+  // Handle all requests. Dispatch + error-shaping logic lives in
+  // request-handler.js so it is unit-testable without starting the transport.
+  server.fallbackRequestHandler = createRequestHandler(tools);
+  return server;
+}
+
+module.exports = { createServer };