outlook-cli 1.2.1 → 1.2.3

package/docs/REFERENCE.md

@@ -11,7 +11,8 @@ This document is the complete, publish-ready reference for:
 - CLI binary: `outlook-cli`
 - Output mode:
   - `text` (default)
-  - `json` (with `--json` or `--output json`)
+  - `json` (with `--json`, `--ai`, or `--output json`)
+- JSON responses include `structured` for normalized, machine-friendly fields while preserving raw `result`.
 - Option key normalization:
   - `--event-id` and `--eventId` map to the same internal key.
   - `--start-server` and `--startServer` are equivalent.
@@ -24,7 +25,9 @@ This document is the complete, publish-ready reference for:
 | Option | Type | Required | Default | Description |
 |---|---|---:|---|---|
 | `--json` | boolean | No | `false` | Forces JSON output for automation and agents. |
+| `--ai` | boolean | No | `false` | Alias for JSON-first agent mode (no rich UI noise). |
 | `--output` | `text` \| `json` | No | `text` | Explicit output mode override. |
+| `--theme` | `k9s` \| `ocean` \| `mono` | No | `k9s` | Text-mode color theme preset. |
 | `--plain` | boolean | No | `false` | Disables rich color and animation UI output. |
 | `--no-color` | boolean | No | `false` | Disables terminal colors. |
 | `--no-animate` | boolean | No | `false` | Disables loading/waiting spinner animation. |
@@ -40,11 +43,13 @@ This document is the complete, publish-ready reference for:
 | `tools list` | Lists all tools with descriptions and schemas. |
 | `tools schema <tool-name>` | Prints schema for one tool. |
 | `call <tool-name>` | Calls any registered MCP tool directly. |
+| `agents guide` | Prints AI-agent workflow guidance and best practices. |
 | `auth ...` | Authentication command group. |
 | `email ...` | Email command group. |
 | `calendar ...` | Calendar command group. |
 | `folder ...` | Folder command group. |
 | `rule ...` | Rules command group. |
+| `mcp-server` | Starts the stdio MCP server (same behavior as `node index.js`). |
 | `doctor` | Environment and auth diagnostics. |
 | `update` | Prints or runs global npm update command. |
 | `help` | Same as `--help`. |
@@ -118,6 +123,18 @@ Examples:
 ```bash
 outlook-cli call list-emails --args-json '{"count":5}'
 outlook-cli call search-emails --arg query=invoice --arg unreadOnly=true --json
+outlook-cli call send-email --args-json '{"to":"a@example.com","subject":"Hi","body":"Hello"}' --ai
+```
+
+### agents guide
+
+Prints AI-agent command patterns and orchestration best practices.
+
+Usage:
+
+```bash
+outlook-cli agents guide
+outlook-cli agents guide --json
 ```
 
 ### auth status
@@ -137,7 +154,7 @@ Prints the Microsoft OAuth URL generated from current config.
 Usage:
 
 ```bash
-outlook-cli auth url
+outlook-cli auth url [--client-id <id>]
 ```
 
 ### auth login
@@ -159,6 +176,27 @@ Options:
 | `--start-server` | boolean | No | `true` | Starts local auth server if not already running. |
 | `--wait` | boolean | No | `true` | Waits for token completion before returning. |
 | `--timeout` | number (seconds) | No | `180` | Max wait time when `--wait` is true. Min effective timeout is 5s. |
+| `--client-id` | string | No | env/config | Runtime override for client ID. |
+| `--client-secret` | string | No | env/config | Runtime override for client secret value. |
+| `--prompt-credentials` | boolean | No | `true` | Prompt for missing credentials in interactive terminals. |
+
+### auth server
+
+Checks or starts the local OAuth callback server.
+
+Usage:
+
+```bash
+outlook-cli auth server --status
+outlook-cli auth server --start
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--status` | boolean | No | `true` when `--start` is not passed | Prints reachability status only. |
+| `--start` | boolean | No | `false` | Starts callback server in background if not running. |
 
 ### auth logout
 

package/email/attachments.js

@@ -0,0 +1,359 @@
+/**
+ * Email attachment listing and retrieval functionality
+ */
+const fs = require('fs');
+const path = require('path');
+const { callGraphAPI, callGraphAPIRaw } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+
+const DEFAULT_ATTACHMENT_COUNT = 25;
+const MAX_ATTACHMENT_COUNT = 50;
+
+function textResponse(text) {
+  return {
+    content: [{
+      type: 'text',
+      text
+    }]
+  };
+}
+
+function asBoolean(value, defaultValue = false) {
+  if (value === undefined || value === null || value === '') {
+    return defaultValue;
+  }
+
+  if (typeof value === 'boolean') {
+    return value;
+  }
+
+  if (typeof value === 'number') {
+    return value !== 0;
+  }
+
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+    return true;
+  }
+
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+    return false;
+  }
+
+  return defaultValue;
+}
+
+function asCount(value, defaultValue = DEFAULT_ATTACHMENT_COUNT) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return defaultValue;
+  }
+
+  return Math.min(parsed, MAX_ATTACHMENT_COUNT);
+}
+
+function getAttachmentKind(rawType) {
+  const type = String(rawType || '').toLowerCase();
+
+  if (type.includes('fileattachment')) {
+    return 'fileAttachment';
+  }
+
+  if (type.includes('itemattachment')) {
+    return 'itemAttachment';
+  }
+
+  if (type.includes('referenceattachment')) {
+    return 'referenceAttachment';
+  }
+
+  return 'attachment';
+}
+
+function sanitizeFileName(value) {
+  const raw = String(value || '').trim();
+  if (!raw) {
+    return 'attachment.bin';
+  }
+
+  const sanitized = raw
+    .replace(/[<>:"/\\|?*\u0000-\u001F]/g, '_')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return sanitized || 'attachment.bin';
+}
+
+function shouldTreatAsDirectory(inputPath) {
+  const value = String(inputPath || '');
+  return value.endsWith(path.sep) || value.endsWith('/') || value.endsWith('\\');
+}
+
+function resolveOutputFilePath(savePath, fallbackFileName) {
+  const requested = String(savePath || '').trim();
+  if (!requested) {
+    return '';
+  }
+
+  const resolved = path.resolve(requested);
+  if (fs.existsSync(resolved)) {
+    const stats = fs.statSync(resolved);
+    if (stats.isDirectory()) {
+      return path.join(resolved, fallbackFileName);
+    }
+
+    return resolved;
+  }
+
+  if (shouldTreatAsDirectory(requested)) {
+    return path.join(resolved, fallbackFileName);
+  }
+
+  return resolved;
+}
+
+function ensureOutputWritable(filePath, overwrite) {
+  if (fs.existsSync(filePath) && !overwrite) {
+    throw new Error(`File already exists at ${filePath}. Re-run with overwrite=true to replace it.`);
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function looksLikeText(buffer) {
+  if (!buffer || buffer.length === 0) {
+    return false;
+  }
+
+  const sampleSize = Math.min(buffer.length, 2048);
+  let printableCount = 0;
+
+  for (let index = 0; index < sampleSize; index += 1) {
+    const byte = buffer[index];
+    const isPrintable = byte === 9 || byte === 10 || byte === 13 || (byte >= 32 && byte <= 126);
+    if (isPrintable) {
+      printableCount += 1;
+    }
+  }
+
+  return (printableCount / sampleSize) >= 0.8;
+}
+
+function buildContentPreview(buffer) {
+  if (!looksLikeText(buffer)) {
+    return '';
+  }
+
+  return buffer
+    .toString('utf8', 0, Math.min(buffer.length, 4096))
+    .slice(0, 600)
+    .trim();
+}
+
+function defaultFileName(attachment, attachmentId) {
+  const kind = getAttachmentKind(attachment['@odata.type']);
+  const fromName = sanitizeFileName(attachment.name || '');
+
+  if (fromName !== 'attachment.bin') {
+    if (kind === 'itemAttachment' && !path.extname(fromName)) {
+      return `${fromName}.eml`;
+    }
+
+    return fromName;
+  }
+
+  if (kind === 'itemAttachment') {
+    return `attachment-${attachmentId}.eml`;
+  }
+
+  return `attachment-${attachmentId}.bin`;
+}
+
+async function getAttachmentBytes(accessToken, messageId, attachment, attachmentId) {
+  const kind = getAttachmentKind(attachment['@odata.type']);
+
+  if (kind === 'referenceAttachment') {
+    throw new Error('Reference attachments are cloud links and cannot be downloaded as raw bytes via this endpoint.');
+  }
+
+  if (kind === 'fileAttachment' && attachment.contentBytes) {
+    return Buffer.from(attachment.contentBytes, 'base64');
+  }
+
+  const rawResponse = await callGraphAPIRaw(
+    accessToken,
+    'GET',
+    `me/messages/${messageId}/attachments/${attachmentId}/$value`
+  );
+
+  return rawResponse.body;
+}
+
+function formatAttachmentLine(attachment, index) {
+  const type = getAttachmentKind(attachment['@odata.type']);
+  const modified = attachment.lastModifiedDateTime
+    ? new Date(attachment.lastModifiedDateTime).toLocaleString()
+    : 'Unknown';
+
+  return `${index + 1}. ${attachment.name || '(unnamed attachment)'}
+ID: ${attachment.id}
+Type: ${type}
+Content Type: ${attachment.contentType || 'unknown'}
+Size: ${attachment.size || 0} bytes
+Inline: ${attachment.isInline ? 'Yes' : 'No'}
+Last Modified: ${modified}`;
+}
+
+/**
+ * List attachments for an email message
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleListAttachments(args = {}) {
+  const messageId = args.messageId || args.id;
+  const count = asCount(args.count, DEFAULT_ATTACHMENT_COUNT);
+
+  if (!messageId) {
+    return textResponse('Message ID is required.');
+  }
+
+  try {
+    const accessToken = await ensureAuthenticated();
+
+    const response = await callGraphAPI(
+      accessToken,
+      'GET',
+      `me/messages/${messageId}/attachments`,
+      null,
+      {
+        $top: count,
+        $select: 'id,name,contentType,size,isInline,lastModifiedDateTime'
+      }
+    );
+
+    const attachments = Array.isArray(response.value) ? response.value : [];
+
+    if (attachments.length === 0) {
+      return textResponse(`No attachments found for message ${messageId}.`);
+    }
+
+    const formatted = attachments
+      .map((attachment, index) => formatAttachmentLine(attachment, index))
+      .join('\n\n');
+
+    return textResponse(`Found ${attachments.length} attachment(s) for message ${messageId}:\n\n${formatted}`);
+  } catch (error) {
+    if (error.message === 'Authentication required') {
+      return textResponse("Authentication required. Please use the 'authenticate' tool first.");
+    }
+
+    return textResponse(`Error listing attachments: ${error.message}`);
+  }
+}
+
+/**
+ * Get one attachment's details and optionally save it to disk
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleGetAttachment(args = {}) {
+  const messageId = args.messageId || args.id;
+  const attachmentId = args.attachmentId;
+  const savePath = args.savePath || args.outputPath || args.out;
+  const includeContent = asBoolean(args.includeContent, false);
+  const expandItem = asBoolean(args.expandItem, false);
+  const overwrite = asBoolean(args.overwrite, false);
+
+  if (!messageId) {
+    return textResponse('Message ID is required.');
+  }
+
+  if (!attachmentId) {
+    return textResponse('Attachment ID is required.');
+  }
+
+  try {
+    const accessToken = await ensureAuthenticated();
+    const queryParams = {};
+
+    if (expandItem) {
+      queryParams.$expand = 'microsoft.graph.itemattachment/item';
+    }
+
+    const attachment = await callGraphAPI(
+      accessToken,
+      'GET',
+      `me/messages/${messageId}/attachments/${attachmentId}`,
+      null,
+      queryParams
+    );
+
+    if (!attachment || !attachment.id) {
+      return textResponse(`Attachment ${attachmentId} not found in message ${messageId}.`);
+    }
+
+    const kind = getAttachmentKind(attachment['@odata.type']);
+    const summary = [
+      `Attachment: ${attachment.name || '(unnamed attachment)'}`,
+      `ID: ${attachment.id}`,
+      `Type: ${kind}`,
+      `Content Type: ${attachment.contentType || 'unknown'}`,
+      `Size: ${attachment.size || 0} bytes`,
+      `Inline: ${attachment.isInline ? 'Yes' : 'No'}`
+    ];
+
+    if (kind === 'referenceAttachment') {
+      const sourceUrl = attachment.sourceUrl || attachment.providerType || 'Unknown';
+      summary.push(`Reference Target: ${sourceUrl}`);
+    }
+
+    if (attachment.item && typeof attachment.item === 'object') {
+      summary.push(`Attached Item Type: ${attachment.item['@odata.type'] || 'unknown'}`);
+      if (attachment.item.subject) {
+        summary.push(`Attached Item Subject: ${attachment.item.subject}`);
+      }
+    }
+
+    let downloadedBuffer = null;
+    if (savePath || includeContent) {
+      downloadedBuffer = await getAttachmentBytes(accessToken, messageId, attachment, attachmentId);
+      summary.push(`Downloaded Bytes: ${downloadedBuffer.length}`);
+    }
+
+    if (savePath) {
+      const destination = resolveOutputFilePath(
+        savePath,
+        defaultFileName(attachment, attachmentId)
+      );
+
+      ensureOutputWritable(destination, overwrite);
+      fs.writeFileSync(destination, downloadedBuffer);
+      summary.push(`Saved To: ${destination}`);
+    }
+
+    if (includeContent && downloadedBuffer) {
+      const preview = buildContentPreview(downloadedBuffer);
+      if (preview) {
+        summary.push('');
+        summary.push('Content Preview:');
+        summary.push(preview);
+      } else {
+        summary.push('');
+        summary.push('Content Preview: Binary content detected (no text preview).');
+      }
+    }
+
+    return textResponse(summary.join('\n'));
+  } catch (error) {
+    if (error.message === 'Authentication required') {
+      return textResponse("Authentication required. Please use the 'authenticate' tool first.");
+    }
+
+    return textResponse(`Error getting attachment: ${error.message}`);
+  }
+}
+
+module.exports = {
+  handleListAttachments,
+  handleGetAttachment
+};

package/email/index.js

@@ -6,6 +6,7 @@ const handleSearchEmails = require('./search');
 const handleReadEmail = require('./read');
 const handleSendEmail = require('./send');
 const handleMarkAsRead = require('./mark-as-read');
+const { handleListAttachments, handleGetAttachment } = require('./attachments');
 
 // Email tool definitions
 const emailTools = [
@@ -144,6 +145,60 @@ const emailTools = [
       required: ["id"]
     },
     handler: handleMarkAsRead
+  },
+  {
+    name: "list-attachments",
+    description: "Lists attachments for a specific email",
+    inputSchema: {
+      type: "object",
+      properties: {
+        messageId: {
+          type: "string",
+          description: "ID of the message that contains attachments"
+        },
+        count: {
+          type: "number",
+          description: "Maximum number of attachments to list (default: 25, max: 50)"
+        }
+      },
+      required: ["messageId"]
+    },
+    handler: handleListAttachments
+  },
+  {
+    name: "get-attachment",
+    description: "Gets one attachment's metadata and optionally downloads it",
+    inputSchema: {
+      type: "object",
+      properties: {
+        messageId: {
+          type: "string",
+          description: "ID of the message that contains the attachment"
+        },
+        attachmentId: {
+          type: "string",
+          description: "ID of the attachment to read or download"
+        },
+        savePath: {
+          type: "string",
+          description: "Optional output file path or output directory path"
+        },
+        includeContent: {
+          type: "boolean",
+          description: "When true, include a text preview for text-like attachments"
+        },
+        expandItem: {
+          type: "boolean",
+          description: "When true, expand item attachment metadata"
+        },
+        overwrite: {
+          type: "boolean",
+          description: "When true, overwrite an existing file at savePath"
+        }
+      },
+      required: ["messageId", "attachmentId"]
+    },
+    handler: handleGetAttachment
   }
 ];
 
@@ -153,5 +208,7 @@ module.exports = {
   handleSearchEmails,
   handleReadEmail,
   handleSendEmail,
-  handleMarkAsRead
+  handleMarkAsRead,
+  handleListAttachments,
+  handleGetAttachment
 };

package/email/search.js

@@ -6,6 +6,12 @@ const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolderPath } = require('./folder-utils');
 
+function debugLog(...args) {
+  if (config.DEBUG_LOGS) {
+    console.error(...args);
+  }
+}
+
 /**
  * Search emails handler
  * @param {object} args - Tool arguments
@@ -27,7 +33,7 @@ async function handleSearchEmails(args) {
     
     // Resolve the folder path
     const endpoint = await resolveFolderPath(accessToken, folder);
-    console.error(`Using endpoint: ${endpoint} for folder: ${folder}`);
+    debugLog(`Using endpoint: ${endpoint} for folder: ${folder}`);
     
     // Execute progressive search
     const response = await progressiveSearch(
@@ -76,16 +82,16 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
   // 1. Try combined search (most specific)
   try {
     const params = buildSearchParams(searchTerms, filterTerms, count);
-    console.error("Attempting combined search with params:", params);
+    debugLog('Attempting combined search with params:', params);
     searchAttempts.push("combined-search");
     
     const response = await callGraphAPI(accessToken, 'GET', endpoint, null, params);
     if (response.value && response.value.length > 0) {
-      console.error(`Combined search successful: found ${response.value.length} results`);
+      debugLog(`Combined search successful: found ${response.value.length} results`);
       return response;
     }
   } catch (error) {
-    console.error(`Combined search failed: ${error.message}`);
+    debugLog(`Combined search failed: ${error.message}`);
   }
   
   // 2. Try each search term individually, starting with most specific
@@ -94,7 +100,7 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
   for (const term of searchPriority) {
     if (searchTerms[term]) {
       try {
-        console.error(`Attempting search with only ${term}: "${searchTerms[term]}"`);
+        debugLog(`Attempting search with only ${term}: "${searchTerms[term]}"`);
         searchAttempts.push(`single-term-${term}`);
         
         // For single term search, only use $search with that term
@@ -118,11 +124,11 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
         
         const response = await callGraphAPI(accessToken, 'GET', endpoint, null, simplifiedParams);
         if (response.value && response.value.length > 0) {
-          console.error(`Search with ${term} successful: found ${response.value.length} results`);
+          debugLog(`Search with ${term} successful: found ${response.value.length} results`);
           return response;
         }
       } catch (error) {
-        console.error(`Search with ${term} failed: ${error.message}`);
+        debugLog(`Search with ${term} failed: ${error.message}`);
       }
     }
   }
@@ -130,7 +136,7 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
   // 3. Try with only boolean filters
   if (filterTerms.hasAttachments === true || filterTerms.unreadOnly === true) {
     try {
-      console.error("Attempting search with only boolean filters");
+      debugLog('Attempting search with only boolean filters');
       searchAttempts.push("boolean-filters-only");
       
       const filterOnlyParams = {
@@ -143,15 +149,15 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
       addBooleanFilters(filterOnlyParams, filterTerms);
       
       const response = await callGraphAPI(accessToken, 'GET', endpoint, null, filterOnlyParams);
-      console.error(`Boolean filter search found ${response.value?.length || 0} results`);
+      debugLog(`Boolean filter search found ${response.value?.length || 0} results`);
       return response;
     } catch (error) {
-      console.error(`Boolean filter search failed: ${error.message}`);
+      debugLog(`Boolean filter search failed: ${error.message}`);
     }
   }
   
   // 4. Final fallback: just get recent emails
-  console.error("All search strategies failed, falling back to recent emails");
+  debugLog('All search strategies failed, falling back to recent emails');
   searchAttempts.push("recent-emails");
   
   const basicParams = {
@@ -161,7 +167,7 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
   };
   
   const response = await callGraphAPI(accessToken, 'GET', endpoint, null, basicParams);
-  console.error(`Fallback to recent emails found ${response.value?.length || 0} results`);
+  debugLog(`Fallback to recent emails found ${response.value?.length || 0} results`);
   
   // Add a note to the response about the search attempts
   response._searchInfo = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outlook-cli",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Production-ready Outlook CLI with optional MCP server mode powered by Microsoft Graph API",
   "keywords": [
     "outlook-cli",