outlook-cli 1.2.1 → 1.2.3

package/cli.js

@@ -22,10 +22,51 @@ const { listTools, getTool, invokeTool } = require('./tool-registry');
 
 const CLI_BIN_NAME = 'outlook-cli';
 const SPINNER_FRAMES = ['|', '/', '-', '\\'];
+const THEMES = Object.freeze({
+  k9s: {
+    title: ['bold', 'cyanBright'],
+    section: ['bold', 'greenBright'],
+    ok: ['bold', 'greenBright'],
+    warn: ['bold', 'yellowBright'],
+    err: ['bold', 'redBright'],
+    muted: ['gray'],
+    accent: ['bold', 'cyan'],
+    key: ['bold', 'whiteBright'],
+    value: ['cyan'],
+    border: ['cyanBright']
+  },
+  ocean: {
+    title: ['bold', 'blueBright'],
+    section: ['bold', 'cyanBright'],
+    ok: ['bold', 'green'],
+    warn: ['bold', 'yellow'],
+    err: ['bold', 'redBright'],
+    muted: ['gray'],
+    accent: ['bold', 'magentaBright'],
+    key: ['bold', 'white'],
+    value: ['blueBright'],
+    border: ['blue']
+  },
+  mono: {
+    title: ['bold', 'white'],
+    section: ['bold', 'white'],
+    ok: ['bold', 'white'],
+    warn: ['bold', 'white'],
+    err: ['bold', 'white'],
+    muted: ['gray'],
+    accent: ['bold', 'white'],
+    key: ['bold', 'white'],
+    value: ['white'],
+    border: ['gray']
+  }
+});
+const DEFAULT_THEME_NAME = 'k9s';
 const UI_STATE = {
   plain: false,
   color: false,
-  animate: false
+  animate: false,
+  themeName: DEFAULT_THEME_NAME,
+  theme: THEMES[DEFAULT_THEME_NAME]
 };
 
 function cliCommand(pathTail = '') {
@@ -207,42 +248,75 @@ function asCsv(value) {
 }
 
 function setUiState(options, outputMode) {
+  const aiMode = asBoolean(readOption(options, 'ai', false), false);
   const plain = asBoolean(readOption(options, 'plain', false), false);
   const colorOption = readOption(options, 'color');
   const animateOption = readOption(options, 'animate');
+  const requestedTheme = String(readOption(
+    options,
+    'theme',
+    process.env.OUTLOOK_CLI_THEME || DEFAULT_THEME_NAME
+  )).trim().toLowerCase();
+  const themeName = THEMES[requestedTheme] ? requestedTheme : DEFAULT_THEME_NAME;
   const isTextMode = outputMode === 'text';
   const isInteractive = isTextMode && process.stdout.isTTY;
 
-  UI_STATE.plain = plain;
-  UI_STATE.color = isInteractive && !plain && colorOption !== false;
-  UI_STATE.animate = isInteractive && !plain && animateOption !== false;
+  UI_STATE.plain = plain || aiMode;
+  UI_STATE.color = isInteractive && !UI_STATE.plain && colorOption !== false;
+  UI_STATE.animate = isInteractive && !UI_STATE.plain && animateOption !== false;
+  UI_STATE.themeName = themeName;
+  UI_STATE.theme = THEMES[themeName];
 
   chalk.level = UI_STATE.color ? Math.max(chalk.level, 1) : 0;
 }
 
-function tone(text, kind) {
-  if (!UI_STATE.color) {
+function applyThemeStyle(text, stylePath) {
+  if (!UI_STATE.color || !stylePath) {
     return text;
   }
 
-  switch (kind) {
-    case 'title':
-      return chalk.bold.cyan(text);
-    case 'section':
-      return chalk.bold.blue(text);
-    case 'ok':
-      return chalk.green(text);
-    case 'warn':
-      return chalk.yellow(text);
-    case 'err':
-      return chalk.red(text);
-    case 'muted':
-      return chalk.gray(text);
-    case 'accent':
-      return chalk.magenta(text);
-    default:
+  const chain = Array.isArray(stylePath) ? stylePath : [stylePath];
+  let painter = chalk;
+
+  for (const segment of chain) {
+    if (!(segment in painter)) {
       return text;
+    }
+
+    painter = painter[segment];
+  }
+
+  return painter(text);
+}
+
+function terminalWidth() {
+  const raw = Number(process.stdout.columns || 100);
+  if (!Number.isFinite(raw)) {
+    return 100;
   }
+
+  return Math.max(72, Math.min(120, raw));
+}
+
+function padRight(value, width) {
+  const text = String(value);
+  if (text.length >= width) {
+    return text;
+  }
+
+  return `${text}${' '.repeat(width - text.length)}`;
+}
+
+function separator(width = terminalWidth()) {
+  return '-'.repeat(Math.max(24, width));
+}
+
+function formatRow(left, right, leftWidth = 34) {
+  return `  ${tone(padRight(left, leftWidth), 'key')} ${tone(right, 'muted')}`;
+}
+
+function tone(text, kind) {
+  return applyThemeStyle(text, UI_STATE.theme[kind]);
 }
 
 function badge(kind) {
@@ -317,9 +391,242 @@ function formatResultText(result) {
   return JSON.stringify(result, null, 2);
 }
 
+function normalizeLineEndings(value) {
+  return String(value || '').replace(/\r\n/g, '\n').trim();
+}
+
+function extractTextChunksFromResult(result) {
+  if (!result || !Array.isArray(result.content)) {
+    return [];
+  }
+
+  return result.content
+    .filter((entry) => entry && entry.type === 'text' && typeof entry.text === 'string')
+    .map((entry) => normalizeLineEndings(entry.text))
+    .filter(Boolean);
+}
+
+function firstNonEmptyLine(text) {
+  const line = normalizeLineEndings(text)
+    .split('\n')
+    .map((entry) => entry.trim())
+    .find(Boolean);
+
+  return line || '';
+}
+
+function parseNumberedBlocks(text) {
+  const normalized = normalizeLineEndings(text);
+  const matches = normalized.match(/\d+\.\s[\s\S]*?(?=(?:\n\d+\.\s)|$)/g);
+  if (!matches) {
+    return [];
+  }
+
+  return matches.map((entry) => entry.trim()).filter(Boolean);
+}
+
+function parseEmailListFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  const body = normalized.replace(/^Found[^\n]*:\n\n?/i, '');
+  const blocks = parseNumberedBlocks(body);
+
+  return blocks.map((block) => {
+    const lines = block.split('\n').map((line) => line.trim()).filter(Boolean);
+    const headline = lines[0] || '';
+    const subjectLine = lines.find((line) => line.startsWith('Subject:')) || '';
+    const idLine = lines.find((line) => line.startsWith('ID:')) || '';
+    const match = headline.match(/^(\d+)\.\s(?:\[UNREAD\]\s)?(.+?)\s-\sFrom:\s(.+?)\s\((.+)\)$/);
+
+    return {
+      index: match ? Number(match[1]) : null,
+      unread: headline.includes('[UNREAD]'),
+      receivedAt: match ? match[2] : null,
+      from: match ? { name: match[3], email: match[4] } : null,
+      subject: subjectLine ? subjectLine.replace(/^Subject:\s*/, '') : null,
+      id: idLine ? idLine.replace(/^ID:\s*/, '') : null,
+      raw: block
+    };
+  });
+}
+
+function parseEventListFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  const body = normalized.replace(/^Found[^\n]*:\n\n?/i, '');
+  const blocks = parseNumberedBlocks(body);
+
+  return blocks.map((block) => {
+    const lines = block.split('\n').map((line) => line.trim()).filter(Boolean);
+    const headline = lines[0] || '';
+    const startLine = lines.find((line) => line.startsWith('Start:')) || '';
+    const endLine = lines.find((line) => line.startsWith('End:')) || '';
+    const summaryLine = lines.find((line) => line.startsWith('Summary:')) || '';
+    const idLine = lines.find((line) => line.startsWith('ID:')) || '';
+    const match = headline.match(/^(\d+)\.\s(.+?)\s-\sLocation:\s(.+)$/);
+
+    return {
+      index: match ? Number(match[1]) : null,
+      subject: match ? match[2] : null,
+      location: match ? match[3] : null,
+      start: startLine ? startLine.replace(/^Start:\s*/, '') : null,
+      end: endLine ? endLine.replace(/^End:\s*/, '') : null,
+      summary: summaryLine ? summaryLine.replace(/^Summary:\s*/, '') : null,
+      id: idLine ? idLine.replace(/^ID:\s*/, '') : null,
+      raw: block
+    };
+  });
+}
+
+function parseFolderListFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  if (normalized.startsWith('Folder Hierarchy:')) {
+    const lines = normalized
+      .replace(/^Folder Hierarchy:\n\n?/i, '')
+      .split('\n')
+      .filter(Boolean);
+
+    return lines.map((line) => {
+      const leadingSpaces = line.match(/^\s*/);
+      const level = leadingSpaces ? Math.floor(leadingSpaces[0].length / 2) : 0;
+      return {
+        level,
+        name: line.trim(),
+        raw: line
+      };
+    });
+  }
+
+  const body = normalized.replace(/^Found[^\n]*:\n\n?/i, '');
+  return body
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line, index) => ({
+      index: index + 1,
+      name: line,
+      raw: line
+    }));
+}
+
+function parseRuleListFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  const body = normalized.replace(/^Found[^\n]*:\n\n?/i, '');
+  const blocks = parseNumberedBlocks(body);
+
+  return blocks.map((block) => {
+    const lines = block.split('\n').map((line) => line.trim()).filter(Boolean);
+    const headline = lines[0] || '';
+    const conditionsLine = lines.find((line) => line.startsWith('Conditions:')) || '';
+    const actionsLine = lines.find((line) => line.startsWith('Actions:')) || '';
+    const match = headline.match(/^(\d+)\.\s(.+?)(?:\s-\sSequence:\s(.+))?$/);
+
+    return {
+      index: match ? Number(match[1]) : null,
+      name: match ? match[2] : null,
+      sequence: match && match[3] ? match[3] : null,
+      conditions: conditionsLine ? conditionsLine.replace(/^Conditions:\s*/, '') : null,
+      actions: actionsLine ? actionsLine.replace(/^Actions:\s*/, '') : null,
+      raw: block
+    };
+  });
+}
+
+function parseReadEmailFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  const sections = normalized.split(/\n\n+/);
+  const headerSection = sections.shift() || '';
+  const headerLines = headerSection.split('\n').map((line) => line.trim()).filter(Boolean);
+  const headers = {};
+
+  headerLines.forEach((line) => {
+    const index = line.indexOf(':');
+    if (index > 0) {
+      const key = line.slice(0, index).trim();
+      const value = line.slice(index + 1).trim();
+      headers[key] = value;
+    }
+  });
+
+  return {
+    headers,
+    body: sections.join('\n\n').trim(),
+    raw: normalized
+  };
+}
+
+function normalizeToolResult(toolName, args, result) {
+  const textChunks = extractTextChunksFromResult(result);
+  const text = textChunks.join('\n\n');
+  const normalized = {
+    tool: toolName,
+    args: args || {},
+    summary: firstNonEmptyLine(text),
+    textChunks
+  };
+
+  switch (toolName) {
+    case 'list-emails':
+    case 'search-emails':
+      normalized.kind = 'email-list';
+      normalized.items = parseEmailListFromText(text);
+      normalized.count = normalized.items.length;
+      return normalized;
+
+    case 'list-events':
+      normalized.kind = 'event-list';
+      normalized.items = parseEventListFromText(text);
+      normalized.count = normalized.items.length;
+      return normalized;
+
+    case 'list-folders':
+      normalized.kind = 'folder-list';
+      normalized.items = parseFolderListFromText(text);
+      normalized.count = normalized.items.length;
+      return normalized;
+
+    case 'list-rules':
+      normalized.kind = 'rule-list';
+      normalized.items = parseRuleListFromText(text);
+      normalized.count = normalized.items.length;
+      return normalized;
+
+    case 'read-email':
+      normalized.kind = 'email-detail';
+      normalized.record = parseReadEmailFromText(text);
+      return normalized;
+
+    default:
+      normalized.kind = 'text';
+      normalized.lines = normalizeLineEndings(text).split('\n').filter(Boolean);
+      return normalized;
+  }
+}
+
+function buildStructuredPayload(payload) {
+  const response = { ...payload };
+
+  if (payload.tool && payload.result) {
+    response.structured = normalizeToolResult(payload.tool, payload.args, payload.result);
+    return response;
+  }
+
+  response.structured = {
+    command: payload.command || null,
+    summary: typeof payload.message === 'string' ? payload.message : null,
+    data: payload.data || null
+  };
+
+  return response;
+}
+
+function printTextBlock(title, body) {
+  process.stdout.write(`${tone(title, 'section')}\n`);
+  process.stdout.write(`${tone(separator(32), 'border')}\n`);
+  process.stdout.write(`${body}\n`);
+}
+
 function printSuccess(outputMode, payload) {
   if (outputMode === 'json') {
-    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify(buildStructuredPayload(payload), null, 2)}\n`);
     return;
   }
 
@@ -328,11 +635,11 @@ function printSuccess(outputMode, payload) {
   }
 
   if (payload.result) {
-    process.stdout.write(`${tone('Result:', 'section')}\n${formatResultText(payload.result)}\n`);
+    printTextBlock('Result', formatResultText(payload.result));
   }
 
   if (payload.data && !payload.result) {
-    process.stdout.write(`${tone('Details:', 'section')}\n${JSON.stringify(payload.data, null, 2)}\n`);
+    printTextBlock('Details', JSON.stringify(payload.data, null, 2));
   }
 }
 
@@ -351,11 +658,16 @@ function printError(outputMode, error) {
 
   process.stderr.write(`${badge('err')} ${error.message}\n`);
   if (error instanceof UsageError) {
-    process.stderr.write(`${tone(`Run '${cliCommand('help')}' to see valid usage.`, 'muted')}\n`);
+    process.stderr.write(`${tone(separator(42), 'border')}\n`);
+    process.stderr.write(`${tone(formatRow('help', `Run '${cliCommand('help')}' to see valid usage.`, 14), 'muted')}\n`);
   }
 }
 
 function buildOutputMode(options) {
+  if (asBoolean(readOption(options, 'ai', false), false)) {
+    return 'json';
+  }
+
   const outputOption = readOption(options, 'output');
   if (outputOption === 'json') {
     return 'json';
@@ -422,43 +734,51 @@ async function callTool(toolName, args, outputMode, commandLabel) {
 function printUsage() {
   const usage = [
     `${tone(CLI_BIN_NAME, 'title')} ${tone(`v${pkg.version}`, 'muted')}`,
+    tone(`Theme: ${UI_STATE.themeName} | AI mode: --ai`, 'muted'),
+    tone(separator(), 'border'),
     '',
-    tone('Global install:', 'section'),
-    `  npm i -g ${pkg.name}`,
+    tone('Install', 'section'),
+    formatRow('global', `npm i -g ${pkg.name}`, 18),
+    formatRow('local', 'npm install', 18),
     '',
-    tone('Usage:', 'section'),
-    `  ${cliCommand('<command> [subcommand] [options]')}`,
+    tone('Usage', 'section'),
+    `  ${tone(cliCommand('<command> [subcommand] [options]'), 'accent')}`,
     '',
-    tone('Global options:', 'section'),
-    '  --json                 Output machine-readable JSON',
-    '  --output text|json     Explicit output mode',
-    '  --plain                Disable rich colors and animations',
-    '  --no-color             Disable colors explicitly',
-    '  --no-animate           Disable spinner animations',
-    '  --help                 Show help',
-    '  --version              Show version',
+    tone('Global options', 'section'),
+    formatRow('--json', 'Machine-readable JSON output'),
+    formatRow('--ai', 'Agent-safe alias for JSON mode (no spinners/colors)'),
+    formatRow('--output text|json', 'Explicit output mode'),
+    formatRow('--theme k9s|ocean|mono', 'Theme preset for text output'),
+    formatRow('--plain', 'Disable rich styling and animations'),
+    formatRow('--no-color', 'Disable colors explicitly'),
+    formatRow('--no-animate', 'Disable spinner animations'),
+    formatRow('--help', 'Show help'),
+    formatRow('--version', 'Show version'),
     '',
-    tone('Core commands:', 'section'),
-    '  commands               Show all command groups and tools',
-    '  tools list',
-    '  tools schema <tool-name>',
-    '  call <tool-name> [--args-json "{...}"] [--arg key=value]',
-    '  auth status|url|login|logout|server',
-    '    auth login [--client-id <id>] [--client-secret <secret>] [--prompt-credentials true|false]',
-    '    auth server [--status] [--start]',
-    '  update [--run] [--to latest|x.y.z]',
-    '  doctor',
+    tone('Core commands', 'section'),
+    formatRow('commands', 'Show command groups and available tools'),
+    formatRow('tools list', 'List all tool names and descriptions'),
+    formatRow('tools schema <tool-name>', 'Show JSON schema for one tool'),
+    formatRow('call <tool-name> [--args-json] [--arg]', 'Invoke any tool directly'),
+    formatRow('auth status|url|login|logout|server', 'Authentication and OAuth server control'),
+    formatRow('agents guide', 'AI agent quick-start and orchestration tips'),
+    formatRow('doctor', 'Run diagnostics and environment checks'),
+    formatRow('update [--run] [--to latest|x.y.z]', 'Check or apply global update'),
+    formatRow('mcp-server', 'Run stdio MCP server (for Claude/Codex/VS Code)'),
     '',
-    tone('Human-friendly command groups:', 'section'),
-    '  email list|search|read|send|mark-read',
-    '  calendar list|create|decline|cancel|delete',
-    '  folder list|create|move',
-    '  rule list|create|sequence',
+    tone('Command groups', 'section'),
+    formatRow('email', 'list|search|read|attachments|attachment|send|mark-read'),
+    formatRow('calendar', 'list|create|decline|cancel|delete'),
+    formatRow('folder', 'list|create|move'),
+    formatRow('rule', 'list|create|sequence'),
     '',
-    tone('Examples:', 'section'),
+    tone('Examples', 'section'),
     `  ${cliCommand('auth login --open --start-server --wait --timeout 180')}`,
-    `  ${cliCommand('email list --folder inbox --count 15')}`,
-    `  ${cliCommand('call search-emails --arg query=invoice --arg unreadOnly=true --json')}`,
+    `  ${cliCommand('auth login --open --client-id <id> --client-secret <secret>')}`,
+    `  ${cliCommand('email attachments --id <message-id>')}`,
+    `  ${cliCommand('email attachment --id <message-id> --attachment-id <attachment-id> --save-path ./downloads/')}`,
+    `  ${cliCommand('agents guide --json')}`,
+    `  ${cliCommand("call list-emails --args-json '{\"folder\":\"inbox\",\"count\":5}' --ai")}`,
     `  ${cliCommand('tools schema send-email')}`,
     `  ${cliCommand('update --run')}`
   ];
@@ -549,13 +869,14 @@ function buildCommandCatalog() {
   return {
     commandGroups: {
       auth: ['status', 'url', 'login', 'logout', 'server'],
-      email: ['list', 'search', 'read', 'send', 'mark-read'],
+      email: ['list', 'search', 'read', 'attachments', 'attachment', 'send', 'mark-read'],
       calendar: ['list', 'create', 'decline', 'cancel', 'delete'],
       folder: ['list', 'create', 'move'],
       rule: ['list', 'create', 'sequence'],
+      agents: ['guide'],
       tools: ['list', 'schema'],
       generic: ['call'],
-      system: ['doctor', 'update', 'version', 'help']
+      system: ['doctor', 'update', 'version', 'help', 'mcp-server']
     },
     tools: toolCatalog
   };
@@ -570,18 +891,21 @@ function printCommandCatalog(outputMode) {
     data: catalog,
     message: outputMode === 'text'
       ? [
-        `Command groups:`,
-        `- auth: ${catalog.commandGroups.auth.join(', ')}`,
-        `- email: ${catalog.commandGroups.email.join(', ')}`,
-        `- calendar: ${catalog.commandGroups.calendar.join(', ')}`,
-        `- folder: ${catalog.commandGroups.folder.join(', ')}`,
-        `- rule: ${catalog.commandGroups.rule.join(', ')}`,
-        `- tools: ${catalog.commandGroups.tools.join(', ')}`,
-        `- generic: ${catalog.commandGroups.generic.join(', ')}`,
-        `- system: ${catalog.commandGroups.system.join(', ')}`,
+        tone('Command groups', 'section'),
+        tone(separator(48), 'border'),
+        formatRow('auth', catalog.commandGroups.auth.join(', '), 14),
+        formatRow('email', catalog.commandGroups.email.join(', '), 14),
+        formatRow('calendar', catalog.commandGroups.calendar.join(', '), 14),
+        formatRow('folder', catalog.commandGroups.folder.join(', '), 14),
+        formatRow('rule', catalog.commandGroups.rule.join(', '), 14),
+        formatRow('agents', catalog.commandGroups.agents.join(', '), 14),
+        formatRow('tools', catalog.commandGroups.tools.join(', '), 14),
+        formatRow('generic', catalog.commandGroups.generic.join(', '), 14),
+        formatRow('system', catalog.commandGroups.system.join(', '), 14),
         '',
-        `Available MCP tools (${catalog.tools.length}):`,
-        ...catalog.tools.map((tool) => `- ${tool.name}`)
+        tone(`Available MCP tools (${catalog.tools.length})`, 'section'),
+        tone(separator(48), 'border'),
+        ...catalog.tools.map((tool) => formatRow(tool.name, tool.description || 'No description', 28))
       ].join('\n')
       : undefined
   });
@@ -1079,6 +1403,36 @@ async function handleEmailCommand(action, options, outputMode) {
       return;
     }
 
+    case 'attachments': {
+      await callTool(
+        'list-attachments',
+        {
+          messageId: requireOption(options, 'id', `Usage: ${cliCommand('email attachments --id <email-id> [--count <number>]')}`),
+          count: asNumber(readOption(options, 'count', 25), 25, 'count')
+        },
+        outputMode,
+        'email attachments'
+      );
+      return;
+    }
+
+    case 'attachment': {
+      await callTool(
+        'get-attachment',
+        {
+          messageId: requireOption(options, 'id', `Usage: ${cliCommand('email attachment --id <email-id> --attachment-id <attachment-id> [--save-path <path>]')}`),
+          attachmentId: requireOption(options, 'attachmentId', `Usage: ${cliCommand('email attachment --id <email-id> --attachment-id <attachment-id> [--save-path <path>]')}`),
+          savePath: readOption(options, 'savePath', readOption(options, 'out')),
+          includeContent: asBoolean(readOption(options, 'includeContent', false), false),
+          expandItem: asBoolean(readOption(options, 'expandItem', false), false),
+          overwrite: asBoolean(readOption(options, 'overwrite', false), false)
+        },
+        outputMode,
+        'email attachment'
+      );
+      return;
+    }
+
     case 'send': {
       await callTool(
         'send-email',
@@ -1111,7 +1465,7 @@ async function handleEmailCommand(action, options, outputMode) {
     }
 
     default:
-      throw new UsageError('Unknown email command. Use: email list|search|read|send|mark-read');
+      throw new UsageError('Unknown email command. Use: email list|search|read|attachments|attachment|send|mark-read');
   }
 }
 
@@ -1290,6 +1644,56 @@ async function handleRuleCommand(action, options, outputMode) {
   }
 }
 
+function startMcpServerProcess() {
+  // eslint-disable-next-line global-require
+  require('./index');
+}
+
+async function handleAgentsCommand(action, outputMode) {
+  const subcommand = action || 'guide';
+  if (subcommand !== 'guide') {
+    throw new UsageError('Unknown agents command. Use: agents guide');
+  }
+
+  const tools = listTools();
+  const guide = {
+    totalTools: tools.length,
+    toolNames: tools.map((tool) => tool.name),
+    mcpServerCommand: `${CLI_BIN_NAME} mcp-server`,
+    recommendedFlow: [
+      `${CLI_BIN_NAME} auth status --json`,
+      `${CLI_BIN_NAME} tools list --json`,
+      `${CLI_BIN_NAME} tools schema <tool-name> --json`,
+      `${CLI_BIN_NAME} call <tool-name> --args-json '{"...":"..."}' --json`
+    ],
+    safetyNotes: [
+      'Prefer --json or --ai for agent workflows.',
+      'Use tools schema before call for strict argument validation.',
+      'Use auth status before calling Microsoft Graph tools.'
+    ]
+  };
+
+  printSuccess(outputMode, {
+    ok: true,
+    command: 'agents guide',
+    data: guide,
+    message: outputMode === 'text'
+      ? [
+        tone('Agent guide', 'section'),
+        tone(separator(48), 'border'),
+        formatRow('mcp server', guide.mcpServerCommand, 18),
+        formatRow('available tools', String(guide.totalTools), 18),
+        '',
+        tone('Recommended workflow', 'section'),
+        ...guide.recommendedFlow.map((line) => `  ${tone(line, 'accent')}`),
+        '',
+        tone('Best practices', 'section'),
+        ...guide.safetyNotes.map((note) => formatRow('note', note, 18))
+      ].join('\n')
+      : undefined
+  });
+}
+
 async function handleDoctorCommand(outputMode) {
   const tokenPath = config.AUTH_CONFIG.tokenStorePath;
   const tokenExists = fs.existsSync(tokenPath);
@@ -1445,6 +1849,11 @@ async function run() {
       await handleGenericCall(positional.slice(1), options, outputMode);
       return;
 
+    case 'agents':
+    case 'agent':
+      await handleAgentsCommand(action, outputMode);
+      return;
+
     case 'auth':
       await handleAuthCommand(action, options, outputMode);
       return;
@@ -1473,6 +1882,10 @@ async function run() {
       await handleUpdateCommand(options, outputMode);
       return;
 
+    case 'mcp-server':
+      startMcpServerProcess();
+      return;
+
     default:
       throw new UsageError(`Unknown command: ${command}. Run '${cliCommand('help')}' for usage.`);
   }