@littlebearapps/outlook-assistant 3.13.0 → 3.14.1

package/request-handler.js

@@ -2,142 +2,243 @@
  * MCP request dispatcher for the Outlook Assistant server.
  *
  * Extracted from index.js so the dispatch + error-shaping logic is
- * unit-testable without starting the stdio transport.
+ * unit-testable without starting the stdio transport. The SDK answers
+ * `initialize` and `ping` itself and negotiates the protocol version; every
+ * other request lands here.
  *
- * IMPORTANT (#213): a `tools/call` that fails MUST return a visible MCP
- * tool-error result (`{ content: [...], isError: true }`). Returning a
- * content-less `{ error: {...} }` object gets coerced by the SDK into
- * `{ content: [] }`, which the client renders as EMPTY OUTPUT — the exact
- * symptom reported for device-code auth in a remote connector session.
+ * Two kinds of failure, kept apart (#276):
+ * - Protocol errors are thrown as McpError, which the SDK sends as a real
+ *   JSON-RPC error: unknown method (-32601), unknown tool (-32602), or a
+ *   failure inside the dispatcher itself (-32603).
+ * - Tool failures (bad arguments, a throwing handler) are returned as a
+ *   visible tool-error result (`{ content: [...], isError: true }`) so the
+ *   model can read them and correct itself. A content-less `{ error }` object
+ *   would be coerced by the SDK into `{ content: [] }`, which clients render
+ *   as EMPTY OUTPUT (#213).
  */
+const { McpError, ErrorCode } = require('@modelcontextprotocol/sdk/types.js');
 const config = require('./config');
 const { coerceArgsAgainstSchema } = require('./utils/schema-coerce');
+const { readOnlyRefusal } = require('./utils/read-only');
+const { riskMeta, supportsDryRun, TOOL_RISK } = require('./utils/risk-classes');
+const { DRY_RUN_LABEL } = require('./utils/safety');
+const { toolError } = require('./utils/tool-error');
+const { log, withCallContext, formatNoteValue } = require('./utils/logger');
 
 /**
- * Build the MCP fallbackRequestHandler for a given tool set.
- * @param {Array<{name: string, description?: string, inputSchema?: object, annotations?: object, handler?: Function}>} TOOLS
- * @returns {(request: object) => Promise<object>}
+ * A visible tool-error result.
+ * @param {string} text
+ * @returns {{content: Array<{type: string, text: string}>, isError: true}}
  */
-function createRequestHandler(TOOLS) {
-  return async (request) => {
-    try {
-      const { method, params, id } = request;
-      console.error(`REQUEST: ${method} [${id}]`);
+function toolErrorResult(text) {
+  return { content: [{ type: 'text', text }], isError: true };
+}
 
-      // Initialize handler
-      if (method === 'initialize') {
-        console.error(`INITIALIZE REQUEST: ID [${id}]`);
-        return {
-          protocolVersion: '2024-11-05',
-          capabilities: {
-            tools: TOOLS.reduce((acc, tool) => {
-              acc[tool.name] = {};
-              return acc;
-            }, {}),
-          },
-          serverInfo: {
-            name: config.SERVER_NAME,
-            version: config.SERVER_VERSION,
-          },
-        };
-      }
+/**
+ * tools/list result: the public fields of every tool (never the handler).
+ * @param {Array<object>} TOOLS
+ */
+function listTools(TOOLS) {
+  log.debug(`tools/list: ${TOOLS.length} tools`);
+  return {
+    tools: TOOLS.map((tool) => {
+      // Client-specific flags derived from the risk map (#271), e.g.
+      // Claude's anthropic/requiresUserInteraction. Others ignore them.
+      const meta = riskMeta(tool.name);
+      return {
+        name: tool.name,
+        ...(tool.title && { title: tool.title }),
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        ...(tool.annotations && { annotations: tool.annotations }),
+        ...(meta && { _meta: meta }),
+      };
+    }),
+  };
+}
 
-      // Tools list handler
-      if (method === 'tools/list') {
-        console.error(`TOOLS LIST REQUEST: ID [${id}]`);
-        console.error(`TOOLS COUNT: ${TOOLS.length}`);
-        console.error(`TOOLS NAMES: ${TOOLS.map((t) => t.name).join(', ')}`);
+/**
+ * The refusal for `dryRun: true` on a call that doesn't honour it (#274), or
+ * null. Handlers for those actions ignore the flag and really write, so the
+ * call never reaches them.
+ * @param {string} toolName
+ * @param {object} args - validated arguments
+ */
+function dryRunRefusal(toolName, args) {
+  if (args.dryRun !== true || supportsDryRun(toolName, args.action)) {
+    return null;
+  }
+  const action = args.action ?? TOOL_RISK[toolName]?.defaultAction;
+  const call = action ? `${toolName} action=${action}` : toolName;
+  return toolError(
+    `dryRun is not supported for ${call}; nothing was changed.`,
+    {
+      nextStep:
+        'Describe the change to the user and ask for confirmation, then call it without dryRun.',
+    }
+  );
+}
 
-        return {
-          tools: TOOLS.map((tool) => ({
-            name: tool.name,
-            description: tool.description,
-            inputSchema: tool.inputSchema,
-            ...(tool.annotations && { annotations: tool.annotations }),
-          })),
-        };
-      }
+/**
+ * Mark a supported dry run's result as a preview: `_meta.dryRun` and the
+ * DRY_RUN_LABEL first line, for handlers that don't set them themselves
+ * (send-email, draft create, manage-rules create/update).
+ * @param {object} result
+ */
+function labelDryRun(result) {
+  if (!result || result.isError) return result;
+  const content = Array.isArray(result.content) ? [...result.content] : [];
+  const first = content[0];
+  if (first?.type === 'text' && !first.text.startsWith(DRY_RUN_LABEL)) {
+    content[0] = { ...first, text: `${DRY_RUN_LABEL}\n\n${first.text}` };
+  }
+  return { ...result, content, _meta: { ...result._meta, dryRun: true } };
+}
 
-      // Required empty responses for other capabilities
-      if (method === 'resources/list') return { resources: [] };
-      if (method === 'prompts/list') return { prompts: [] };
+/**
+ * Run a tool's handler with validated arguments, unless read-only mode
+ * (#271) or an unsupported dryRun (#274) refuses the call first. Read-only
+ * mode is checked first, so it refuses even a supported dry run of a
+ * non-read call.
+ * @param {object} tool
+ * @param {object} args
+ */
+async function runTool(tool, args) {
+  if (config.READ_ONLY) {
+    const refusal = readOnlyRefusal(tool.name, args);
+    if (refusal) return refusal;
+  }
+  const refusal = dryRunRefusal(tool.name, args);
+  if (refusal) return refusal;
+  const result = await tool.handler(args);
+  return args.dryRun === true ? labelDryRun(result) : result;
+}
 
-      // Tool call handler
-      if (method === 'tools/call') {
-        try {
-          const { name, arguments: args = {} } = params || {};
+/**
+ * The action to show on the call line: only a value from the tool's own
+ * `action` enum, `?` for anything else, so free text never reaches the log.
+ * @param {object|undefined} tool
+ * @param {object} args
+ * @returns {string|undefined}
+ */
+function loggableAction(tool, args) {
+  const action = args && args.action;
+  if (action === undefined) return undefined;
+  const allowed = tool?.inputSchema?.properties?.action?.enum;
+  return Array.isArray(allowed) && allowed.includes(action) ? action : '?';
+}
 
-          console.error(`TOOL CALL: ${name}`);
+/**
+ * The one default-level line per tool call (#278): tool name, action,
+ * outcome and duration, plus any notes (e.g. a Graph status) collected
+ * during the call. Never the arguments.
+ */
+function logToolCall({ tool, action, outcome, startedAt, notes }) {
+  const parts = [`tool=${tool}`];
+  if (action !== undefined) parts.push(`action=${action}`);
+  parts.push(`outcome=${outcome}`, `ms=${Date.now() - startedAt}`);
+  for (const [key, value] of notes) {
+    parts.push(`${key}=${formatNoteValue(value)}`);
+  }
+  log.info(parts.join(' '));
+}
 
-          // Find the tool handler
-          const tool = TOOLS.find((t) => t.name === name);
+/**
+ * tools/call: validate arguments, then run the tool's handler. Logs one
+ * line per call (see logToolCall).
+ * @param {Array<object>} TOOLS
+ * @param {object} [params]
+ */
+function callTool(TOOLS, params) {
+  const { name, arguments: args = {} } = params || {};
+  const tool = TOOLS.find((t) => t.name === name);
+  const startedAt = Date.now();
 
-          if (tool && tool.handler) {
-            // Coerce + validate args against the tool's inputSchema before
-            // dispatching. Catches array-as-string, boolean-as-string, unknown
-            // params, and out-of-enum action values at the MCP boundary so
-            // handlers receive properly-typed JS values. (#160, #162)
-            if (tool.inputSchema) {
-              const coerced = coerceArgsAgainstSchema(args, tool.inputSchema);
-              if (coerced.error) {
-                return {
-                  content: [
-                    {
-                      type: 'text',
-                      text: `Invalid arguments for tool '${name}':\n${coerced.error}`,
-                    },
-                  ],
-                  isError: true,
-                };
-              }
-              return await tool.handler(coerced.args);
-            }
-            return await tool.handler(args);
-          }
+  return withCallContext(async (ctx) => {
+    const line = {
+      tool: tool ? name : '?',
+      action: loggableAction(tool, args),
+      startedAt,
+      notes: ctx.notes,
+    };
+    if (!tool || !tool.handler) {
+      logToolCall({ ...line, outcome: 'unknown-tool' });
+      throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
+    }
+    log.debug(
+      `tools/call ${name} args: ${Object.keys(args || {}).join(', ') || '(none)'}`
+    );
 
-          // Tool not found — return visible isError content, not a
-          // content-less { error } (which renders as empty output). (#213)
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Tool not found: ${name}`,
-              },
-            ],
-            isError: true,
-          };
-        } catch (error) {
-          console.error(`Error in tools/call:`, error);
-          // Surface the failure as visible tool-error content so it is not
-          // silently rendered as empty output by the client. (#213)
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Error processing tool call: ${error.message}`,
-              },
-            ],
-            isError: true,
-          };
-        }
+    const { result, error } = await runToolCall(tool, name, args);
+    if (error) {
+      // Class name only (e.g. TypeError): the message can carry user data.
+      const errorClass = /^[A-Za-z]{1,40}$/.test(error?.name)
+        ? error.name
+        : 'Error';
+      ctx.notes.set('error', errorClass);
+      logToolCall({ ...line, outcome: 'thrown' });
+    } else {
+      logToolCall({ ...line, outcome: result?.isError ? 'isError' : 'ok' });
+    }
+    return result;
+  });
+}
+
+/**
+ * Coerce and validate the arguments, then run the handler.
+ * @returns {Promise<{result: object, error?: Error}>}
+ */
+async function runToolCall(tool, name, args) {
+  try {
+    // Coerce + validate args against the tool's inputSchema before
+    // dispatching. Catches array-as-string, boolean-as-string, unknown
+    // params, and out-of-enum action values at the MCP boundary so
+    // handlers receive properly-typed JS values. (#160, #162)
+    if (tool.inputSchema) {
+      const coerced = coerceArgsAgainstSchema(args, tool.inputSchema);
+      if (coerced.error) {
+        return {
+          result: toolErrorResult(
+            `Invalid arguments for tool '${name}':\n${coerced.error}`
+          ),
+        };
       }
+      return { result: await runTool(tool, coerced.args) };
+    }
+    return { result: await runTool(tool, args) };
+  } catch (error) {
+    log.debug('Error in tools/call:', error);
+    return {
+      result: toolErrorResult(`Error processing tool call: ${error.message}`),
+      error,
+    };
+  }
+}
 
-      // For any other method, return method not found
-      return {
-        error: {
-          code: -32601,
-          message: `Method not found: ${method}`,
-        },
-      };
+/**
+ * Build the MCP fallbackRequestHandler for a given tool set.
+ * @param {Array<{name: string, title?: string, description?: string, inputSchema?: object, annotations?: object, handler?: Function}>} TOOLS
+ * @returns {(request: object) => Promise<object>}
+ */
+function createRequestHandler(TOOLS) {
+  return async (request) => {
+    const { method, params, id } = request;
+    log.debug(`REQUEST: ${method} [${id}]`);
+
+    try {
+      if (method === 'tools/list') return listTools(TOOLS);
+      if (method === 'tools/call') return await callTool(TOOLS, params);
     } catch (error) {
-      console.error(`Error in fallbackRequestHandler:`, error);
-      return {
-        error: {
-          code: -32603,
-          message: `Error processing request: ${error.message}`,
-        },
-      };
+      if (error instanceof McpError) throw error;
+      log.info(`Error in fallbackRequestHandler: ${error.name || 'Error'}`);
+      log.debug('Error in fallbackRequestHandler:', error);
+      throw new McpError(
+        ErrorCode.InternalError,
+        `Error processing request: ${error.message}`
+      );
     }
+
+    throw new McpError(ErrorCode.MethodNotFound, `Method not found: ${method}`);
   };
 }
 

package/rules/create.js

@@ -3,16 +3,17 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
-const { checkRateLimit } = require('../utils/safety');
-const { formatRuleDryRunPreview } = require('../utils/safety');
+const { checkRateLimit, formatRuleDryRunPreview } = require('../utils/safety');
 const { getInboxRules } = require('./list');
 const {
   buildConditions,
   buildActions,
   buildExceptions,
+  checkRuleRecipients,
   hasAnyCondition,
   hasAnyAction,
 } = require('./rule-builder');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Create rule handler
@@ -22,55 +23,31 @@ const {
 async function handleCreateRule(args) {
   const { name, isEnabled = true, sequence, dryRun } = args;
 
-  // Rate limit rule creation
-  const rateLimitError = checkRateLimit('manage-rules');
-  if (rateLimitError) return rateLimitError;
-
   // Validate sequence parameter
   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.');
   }
 
   if (!name) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Rule name is required.',
-        },
-      ],
-    };
+    return toolError('Rule name is required.');
   }
 
   if (!hasAnyCondition(args)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'At least one condition is required. Available conditions: fromAddresses, containsSubject, bodyContains, bodyOrSubjectContains, senderContains, recipientContains, sentToAddresses, hasAttachments, importance, sensitivity, sentToMe, sentOnlyToMe, sentCcMe, isAutomaticReply.',
-        },
-      ],
-    };
+    return toolError(
+      'At least one condition is required. Available conditions: fromAddresses, containsSubject, bodyContains, bodyOrSubjectContains, senderContains, recipientContains, sentToAddresses, hasAttachments, importance, sensitivity, sentToMe, sentOnlyToMe, sentCcMe, isAutomaticReply.'
+    );
   }
 
   if (!hasAnyAction(args)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'At least one action is required. Available actions: moveToFolder, copyToFolder, markAsRead, markImportance, forwardTo, redirectTo, assignCategories, stopProcessingRules, deleteMessage.',
-        },
-      ],
-    };
+    return toolError(
+      'At least one action is required. Available actions: moveToFolder, copyToFolder, markAsRead, markImportance, forwardTo, redirectTo, assignCategories, stopProcessingRules, deleteMessage.'
+    );
   }
 
+  // Refuse the whole rule if the allowlist blocks any forwarding (#273)
+  const recipientError = checkRuleRecipients(args, { dryRun });
+  if (recipientError) return recipientError;
+
   try {
     const accessToken = await ensureAuthenticated();
 
@@ -87,14 +64,9 @@ async function handleCreateRule(args) {
     // Check for fatal warnings (folder not found = no valid action)
     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')
+      );
     }
 
     // Determine sequence
@@ -132,7 +104,7 @@ async function handleCreateRule(args) {
     // Dry-run: preview without creating
     if (dryRun) {
       const preview = formatRuleDryRunPreview(rule);
-      let text = `DRY RUN — Rule preview (not created):\n\n${preview}`;
+      let text = `Rule preview (not created):\n\n${preview}`;
       if (allWarnings.length > 0) {
         text += `\n\nWarnings:\n${allWarnings.map((w) => `- ${w}`).join('\n')}`;
       }
@@ -141,6 +113,10 @@ async function handleCreateRule(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;
+
     // Create the rule
     const response = await callGraphAPI(
       accessToken,
@@ -167,34 +143,15 @@ async function handleCreateRule(args) {
       };
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "Failed to create rule. The server didn't return a rule ID.",
-        },
-      ],
-    };
+    return toolError(
+      "Failed to create rule. The server didn't return a rule ID."
+    );
   } 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 creating rule: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error creating rule: ${error.message}`);
   }
 }