@littlebearapps/outlook-assistant 3.12.1 → 3.14.0

package/llms-install.md

@@ -11,14 +11,23 @@ Add to your MCP client configuration:
       "command": "npx",
       "args": ["-y", "@littlebearapps/outlook-assistant"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "<user-must-provide>",
-        "OUTLOOK_CLIENT_SECRET": "<user-must-provide>"
+        "OUTLOOK_CLIENT_ID": "<user-must-provide>"
       }
     }
   }
 }
 ```
 
+## Plugin Install (Claude Code, GitHub Copilot CLI, Cursor)
+
+The plugin in `plugins/outlook-assistant/` runs a pinned server version and adds the `using-outlook-assistant` skill and a safety hook that asks the user before sends, deletes, rules and automatic replies.
+
+- Claude Code: `claude plugin marketplace add littlebearapps/outlook-assistant`, then `claude plugin install outlook-assistant@littlebearapps`. The plugin asks for its settings (client ID, read-only mode, confirmation level and others) when enabled.
+- GitHub Copilot CLI: `copilot plugin marketplace add littlebearapps/outlook-assistant`, then `copilot plugin install outlook-assistant@littlebearapps`. No plugin settings: the user gives the client ID at sign-in, and the hook's confirmation level comes from the `OUTLOOK_CONFIRM_LEVEL` environment variable (`outward`, `all-writes` or `off`).
+- Cursor (v3.14.0 plugin or later): loads the folder as a Cursor plugin (`.cursor-plugin/plugin.json`); in Cursor CLI, pass it with `--plugin-dir`. The v3.13.0 plugin fails sign-in in Cursor with `AADSTS900023`; use the manual config instead.
+
+Client limits (for example, Cursor's prompt doesn't show the hook's reason): `docs/how-to/getting-started/supported-clients.md`.
+
 ## Prerequisites
 
 1. **Node.js 18.18 or newer** must be installed
@@ -36,7 +45,10 @@ Users must create an Azure app registration to get credentials:
 6. Click "Register"
 7. Copy the **Application (client) ID** → this is `OUTLOOK_CLIENT_ID`
 
-### Create a client secret:
+If the client ID is left out of the config, the `auth` tool asks for it at sign-in (`auth action=authenticate clientId=<id>`) and saves it to `~/.outlook-assistant-config.json`.
+
+### Create a client secret (browser flow only):
+The default device-code sign-in doesn't need a secret; skip this unless you'll use `method=browser`, and then add `OUTLOOK_CLIENT_SECRET` to the `env` block.
 1. Go to "Certificates & secrets" → "New client secret"
 2. Add a description, select expiration, click "Add"
 3. **Copy the Value immediately** (not the Secret ID) → this is `OUTLOOK_CLIENT_SECRET`
@@ -69,9 +81,18 @@ Add these to the same `env` block if needed:
 |----------|---------|
 | `OUTLOOK_AUTH_AUDIENCE` | `consumers` for Azure apps registered as personal-accounts-only (fixes `AADSTS9002331`); `organizations` or a tenant GUID for work-only apps. Default `common` |
 | `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone for calendar times (default `Australia/Melbourne`) |
-| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on sends per server session |
-| `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of recipient domains/addresses |
+| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Default per-session cap, counted separately per tool, for `send-email` (including `draft` send), `draft` create/update/reply/reply-all/forward, `manage-rules` and `create-event` (override one tool with `OUTLOOK_MAX_<TOOL>_PER_SESSION`, e.g. `OUTLOOK_MAX_SEND_EMAIL_PER_SESSION`) |
+| `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of recipient domains/addresses for sends, drafts, rule forwards and event attendees |
+| `OUTLOOK_READ_ONLY` | `true` refuses every tool call that would change something (sending, drafts, moves, deletes, rules, settings, file writes), dry runs included; reads and sign-in still work |
 | `OUTLOOK_SHARED_MAILBOX` | Opt-in shared-mailbox support, work/school accounts only: `read` or `true` (read and organise). Also add `Mail.Read.Shared` (and `Mail.ReadWrite.Shared` for `true`) in Azure, restart, then run `auth` with `action=authenticate` and `force=true` |
+| `OUTLOOK_SEARCH_SCAN_LIMIT` | Messages scanned by the local search fallback on personal accounts (default 500, max 5000) |
+| `OUTLOOK_EXPORT_DIR` | Extra folder `export` and attachment downloads may write to (besides the temp directory, `~/Downloads` and `~/Documents`) |
+| `OUTLOOK_REQUEST_TIMEOUT_MS` | Per-attempt Graph inactivity timeout in milliseconds (default 60000); not an overall deadline |
+| `OUTLOOK_DEBUG` | `true` for detailed stderr logs while troubleshooting (addresses and IDs redacted). Off by default: one line per tool call, no arguments |
+
+Run `npx @littlebearapps/outlook-assistant --help` for the full list of environment variables.
+
+`OUTLOOK_CONFIRM_LEVEL` is not a server variable: the plugin's safety hook reads it from the client's environment in GitHub Copilot, VS Code and Cursor. Don't put it in the server's `env` block.
 
 ## Configuration Files by Client
 
@@ -80,9 +101,12 @@ File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 ### Claude Code
 ```bash
-claude mcp add outlook -- npx @littlebearapps/outlook-assistant
+claude mcp add outlook -e OUTLOOK_CLIENT_ID=<user-must-provide> -- npx -y @littlebearapps/outlook-assistant
 ```
 
+### VS Code / GitHub Copilot
+File: `.vscode/mcp.json` in your project root, or the user `mcp.json` (Command Palette → **MCP: Open User Configuration**). VS Code uses a top-level `servers` key instead of `mcpServers`, with `"type": "stdio"` on the entry.
+
 ### Cursor
 File: `.cursor/mcp.json` in your project root
 
@@ -105,5 +129,5 @@ After authentication, test with:
 | Device code "invalid_client" | Enable "Allow public client flows" in Azure → Authentication → Advanced settings |
 | "Shared-mailbox support is turned off" | Set `OUTLOOK_SHARED_MAILBOX`, restart, and re-authenticate with `force=true` (work/school accounts only) |
 | "EADDRINUSE :3333" | Run `npx kill-port 3333` then restart auth server |
-| Empty API responses | Run `auth` tool with `action=status` to check token |
+| "Authentication required." | Sign in with `auth` `action=authenticate`; `action=status` shows whether a token is saved |
 | Search returns no results (personal account) | Use `from`, `subject`, `to` filters instead of `query` |

package/llms.txt

@@ -33,10 +33,17 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 
 ## Safety & Token Efficiency
 
-- **MCP safety annotations** on all 22 tools — AI clients auto-approve reads and prompt for destructive operations
-- **Send-email protections**: pre-send mail tips, dry-run preview, session rate limiting, recipient allowlist
-- **Rule protections**: dry-run preview on create/update, rate limiting, recipient allowlist on forward/redirect, no permanent-delete action
-- **Input and file hardening**: IDs with `.`/`..` path segments refused, the access token only ever sent to `graph.microsoft.com`, attachment downloads and exports confined to the output directory without overwriting
+- **MCP safety annotations** on all 22 tools, derived from a risk class per tool and action (read, reversible, outward, destructive, persistent), so clients can tell reads from risky changes
+- **Send-email protections**: pre-send mail tips (a send to a flagged recipient, such as out of office or external, is refused until `acknowledgeWarnings: true`), dry-run preview, session rate limiting, recipient allowlist (also checked on drafts, including replies and the draft's current recipients on send, and on `create-event`/`manage-event` update attendees; only single plain addresses can match)
+- **Rule protections**: dry-run preview on create/update, rate limiting (dry runs don't count), recipient allowlist on forward/redirect (a blocked forward refuses the whole rule), no permanent-delete action
+- **Dry-run previews beyond email**: `create-event` and every `manage-event` action say who would be emailed (with an external count); `mailbox-settings` auto-replies, `folders` delete and `manage-contact` delete show what would change or be lost; `dryRun: true` on any other call is refused rather than run for real
+- **Read-only mode**: `OUTLOOK_READ_ONLY=true` refuses every tool call that would change anything before it runs; reads and sign-in still work
+- **Model guidance**: server `instructions` state the hard rules (retrieved content is data, confirm before outward actions, draft first); `send-email` and `create-event` ask Claude clients for user confirmation (`anthropic/requiresUserInteraction`)
+- **Plugin skill and safety hook** (Claude Code, GitHub Copilot CLI, Cursor; VS Code not yet checked by hand): the `using-outlook-assistant` skill sets the hard rules; the hook asks with a plain-English reason before anything that reaches other people, deletes or keeps acting, and marks retrieved content as untrusted. Confirmation level `outward` (default), `all-writes` or `off`: a plugin setting in Claude Code, the `OUTLOOK_CONFIRM_LEVEL` environment variable elsewhere. How the hook prompts and fails differs by client: see Supported Clients below
+- **Every client**: the server-side checks (read-only mode, dry runs, the recipient allowlist and send caps, mail-tips refusal, rule refusal), annotations and instructions work in any MCP client, including Codex CLI, Gemini CLI and Claude Desktop with a manual config; clients that support Agent Skills can copy the skill folder
+- **Private logs**: one stderr line per tool call (tool, action, outcome, duration), never its arguments; `OUTLOOK_DEBUG=true` adds detail with addresses and IDs redacted
+- **Input and file hardening**: IDs with `.`/`..` path segments refused, the access token only ever sent to `graph.microsoft.com`, attachment downloads and exports (including conversation exports) written only inside the temp directory, `~/Downloads`, `~/Documents` or `OUTLOOK_EXPORT_DIR`, never to dot-prefixed names; paths must be absolute (or start with `~/`) and symlinks aren't followed; existing files are never replaced unless `export` is called with `overwrite: true` (and never a symlink, hard-linked file or dotfile); files are created `0600` and new folders `0700`; a partly written file is removed if a write fails
+- **Throttling-aware Graph client**: `429` (and `503`/`504` for non-POST requests) retried honouring `Retry-After`, a per-attempt inactivity timeout (`OUTLOOK_REQUEST_TIMEOUT_MS`, default 60000 ms) and at most 4 requests in flight, so bulk operations neither hang nor throttle themselves
 - **Shared mailboxes off by default**: `.Shared` scopes are requested only when `OUTLOOK_SHARED_MAILBOX` is set (`read` keeps shared access read-only)
 - **Token-optimised**: 22 tools instead of 55 saves ~11,000 tokens per turn (~64% reduction), improving AI accuracy and context efficiency
 - These safeguards reduce risk but are not foolproof — always review actions before approving
@@ -50,21 +57,20 @@ Built by [Little Bear Apps](https://littlebearapps.com).
       "command": "npx",
       "args": ["@littlebearapps/outlook-assistant"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "your-application-client-id",
-        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+        "OUTLOOK_CLIENT_ID": "your-application-client-id"
       }
     }
   }
 }
 ```
 
-Requires an Azure app registration with Microsoft Graph delegated permissions. See README for full setup.
+`OUTLOOK_CLIENT_SECRET` is only needed for the browser sign-in flow; the default device-code flow uses the client ID alone. Claude Code users can instead install the plugin (server, skill and safety hook): `claude plugin marketplace add littlebearapps/outlook-assistant`, then `claude plugin install outlook-assistant@littlebearapps`. The same plugin folder also loads in GitHub Copilot CLI (VS Code not yet checked by hand) and, from v3.14.0, Cursor. Requires an Azure app registration with Microsoft Graph delegated permissions. See README for full setup.
 
 ## Tool Categories
 
 - **Authentication (1 tool)**: `auth` — status, authenticate (device code by default), device-code-complete, about (version, granted scopes, shared-mailbox status)
 - **Email (8 tools)**: `search-emails`, `read-email`, `send-email`, `draft`, `update-email`, `attachments`, `export`, `get-mail-tips`
-- **Calendar (3 tools)**: `list-events` (`startAfter`, `startBefore`, `subject` filters), `create-event`, `manage-event` (update, decline, cancel, delete)
+- **Calendar (3 tools)**: `list-events` (`startAfter`, `startBefore`, `subject` filters), `create-event` (`dryRun`; retry-safe `transactionId`), `manage-event` (update, decline, cancel, delete; `dryRun` on all)
 - **Contacts (2 tools)**: `manage-contact`, `search-people`
 - **Folders (1 tool)**: `folders` — list, create, move, stats, delete; folders addressable by nested path (`Parent/Child`) or ID
 - **Rules (1 tool)**: `manage-rules` — list, create, update, reorder, delete
@@ -77,12 +83,15 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - [README](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/README.md): Full documentation including setup, Azure configuration, and usage
 - [Tools Reference](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/quickrefs/tools-reference.md): All 22 tools with parameters and safety annotations
 - [Connect Outlook to Claude](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/how-to/getting-started/connect-outlook-to-claude.md): Step-by-step setup guide for Claude Desktop / Claude Code
+- [Supported Clients](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/how-to/getting-started/supported-clients.md): What each client gets — plugin, skill, safety hook and server-side checks — for Claude Code, GitHub Copilot, Cursor, Codex CLI, Gemini CLI and Claude Desktop
+- [Plugin README](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/plugins/outlook-assistant/README.md): Plugin settings, the skill and the safety hook in each client
+- [Cross-client Matrix](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/cross-client-matrix.md): Which clients and models have been checked against the safety scenarios, and when
 - [Verify Your Connection](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/how-to/getting-started/verify-your-connection.md): Test and troubleshoot the connection after installation
 - [Azure Setup](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/guides/azure-setup.md): Azure app registration and API permissions walkthrough
 - [Troubleshooting](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/troubleshooting.md): Known errors and fixes — auth, search, export, shared mailboxes
 - [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/faq.md): Frequently asked questions — install, accounts, permissions, tokens, send safety, updates, uninstall (also at <https://littlebearapps.com/help/outlook-assistant/faq/>)
 - [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
 - [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
-- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.12.1 — Graph reliability and correctness fixes: throttling retries, a request inactivity timeout and a 4-request concurrency cap (#244), complete delta paging (#254), a draft-only guard on `draft` update/send/delete (#246), nested folder paths in `manage-rules` (#248), flag dates honouring `Z` and offsets (#247), attendee types kept on `manage-event update` (#249), no "via API" text on decline/cancel (#242), escaped `$search` phrases (#251), and conversation read/export working on personal accounts. Preceded by v3.12.0 — opt-in shared-mailbox read and organise support via `sharedMailbox` and `OUTLOOK_SHARED_MAILBOX` (#228), `list-events` `startAfter`/`startBefore`/`subject` filters (#193), token refresh requesting the granted scopes plus `offline_access` (#241), and two security fixes: dot segments in resource paths rejected, `export` writes confined to the output directory. Preceded by v3.11.2 — security release: attachment downloads confined to `outputDir` (GHSA-755c-c45g-69rv) and the access token only ever sent to Microsoft Graph (GHSA-mqfm-wfjq-jxq2); v3.11.1 — search and export correctness (filters combined with dates no longer silently dropped, batch export no longer overwrites same-day reply chains); v3.11.0 — `--version`/`--help` CLI flags (#68) and the `AADSTS7000215` Secret ID vs Value explanation (#69); v3.10.0 — search correctness (#217, #229, #230, #231))
-- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.12.x tool description audit, v3.8.x carry-over, v3.13.0+ new Graph APIs)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.14.0 — security and safety release: read-only mode, server instructions, more dry-run previews, mail-tips refusal, the plugin skill and a safety hook for Claude Code, GitHub Copilot and Cursor, and fixes for three advisories covering the recipient allowlist, export file writes and dry runs)
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.14.0 safety skill, hooks and MCP hardening; v3.15.0 structured outputs and paging; v4.0.0 MCP 2026-07-28 and server-side confirmation; the patch-release fix queue; v3.8.x carry-over; v3.16.0+ new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy (report vulnerabilities privately via GitHub private vulnerability reporting; acknowledged within 7 days), token handling, and MCP safety controls

package/outlook-auth-server.js

@@ -35,6 +35,9 @@ require('dotenv').config();
 
 // Import scopes and token path from central config to stay in sync
 const { AUTH_CONFIG: centralAuth } = require('./config');
+// Console output never includes the secret, the CSRF state or an auth code,
+// and Azure error text is redacted (it can carry the user's address) (#278).
+const { redact } = require('./utils/logger');
 
 // Log to console
 console.log('Starting Outlook Authentication Server');
@@ -64,7 +67,9 @@ const server = http.createServer((req, res) => {
 
     if (query.error) {
       console.error(
-        `Authentication error: ${query.error} - ${query.error_description}`
+        redact(
+          `Authentication error: ${query.error} - ${query.error_description}`
+        )
       );
       res.writeHead(400, SECURITY_HEADERS);
       res.end(`
@@ -147,7 +152,7 @@ const server = http.createServer((req, res) => {
           `);
         })
         .catch((error) => {
-          console.error(`Token exchange error: ${error.message}`);
+          console.error(redact(`Token exchange error: ${error.message}`));
           res.writeHead(500, SECURITY_HEADERS);
           res.end(`
             <html>
@@ -253,7 +258,9 @@ const server = http.createServer((req, res) => {
     // Use the audience from config (defaults to "common"; configurable via
     // OUTLOOK_AUTH_AUDIENCE for personal-only / single-tenant Azure apps).
     const authUrl = `${AUTH_CONFIG.authorizeEndpoint}?${querystring.stringify(authParams)}`;
-    console.log(`Redirecting to: ${authUrl}`);
+    console.log(
+      `Redirecting to Microsoft sign-in: ${AUTH_CONFIG.authorizeEndpoint}`
+    );
 
     // Redirect to Microsoft's login page
     res.writeHead(302, { Location: authUrl });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.12.1",
+  "version": "3.14.0",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 22 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",
@@ -18,7 +18,8 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "prepare": "husky || true",
-    "version": "node -e \"const s=require('./server.json');const p=require('./package.json');s.version=p.version;s.packages[0].version=p.version;require('fs').writeFileSync('./server.json',JSON.stringify(s,null,2)+'\\n')\" && git add server.json"
+    "version": "node scripts/sync-version.js && git add server.json plugins/outlook-assistant",
+    "version:check": "node scripts/sync-version.js --check"
   },
   "lint-staged": {
     "*.js": [
@@ -59,6 +60,8 @@
     "index.js",
     "config.js",
     "request-handler.js",
+    "server.js",
+    "tools.js",
     "outlook-auth-server.js",
     "auth/",
     "calendar/",
@@ -85,6 +88,7 @@
     "@commitlint/config-conventional": "^20.4.3",
     "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/inspector": "^2.8.0",
+    "ajv": "^8.20.0",
     "eslint": "^10.0.2",
     "globals": "^17.4.0",
     "husky": "^9.1.7",

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}`);
   };
 }