feat(cli): add call subcommand for one-shot tool invocation

[stevenobiajulu]

Summary

• Add email-agent-mcp call <tool> --args '<json>' so MCP tools can be invoked one-shot from a fresh process — no long-lived MCP host required.
• Sidesteps the "code change → restart Claude Code → MCP picks up new build" cycle. Side benefit: tools become scriptable from cron, launchd, hooks, and shell pipelines.
• Also exposes --list (enumerate tools) and --schema (print input JSON Schema), and accepts args via --args / --args-file / --args-stdin.

Closes #72.

Architecture

Extracted executeTool() in server.ts as the shared dispatch primitive. handleToolCall() (MCP transport) becomes a thin wrapper that calls executeTool() then formats the result into the MCP content envelope (preserving the download_attachment resource special-case). runCall() in the CLI calls executeTool() then writes raw JSON to stdout.

This keeps serve and call parity by construction — they share the same action registry and the dispatch path. Only the output formatting diverges.

Differences vs. serve:

• Eager provider init (no demo-mode fallback) — auth failures surface as exit codes instead of masquerading as connecting results
• Snapshot allowlist (no WatchedAllowlist FS watcher in a one-shot process)

Output

• stdout = JSON tool result (pretty-printed for TTY, compact for pipe via process.stdout.isTTY)
• stderr = logs / errors only, so call ... | jq works
• Exit codes:
  • 0 success
  • 2 CLI / argument / schema / unknown-tool error
  • 3 typed tool failure ({success:false,...}) or runtime throw

Out of scope (per peer review with Codex + Gemini)

• Schema-generated per-tool flags — heterogeneous tool inputs, low ROI vs. the --args JSON path
• JSON-RPC over stdin as a public surface — confusing UX, requires MCP envelope knowledge; keep as internal debug if useful later
• Cross-process token-refresh locking — existing single-flight is process-local; mostly fine for read-path call invocations, low risk

Test plan

• 5 new openspec scenarios under cli/Call Subcommand + cli/Exit Codes
• Unit: parseCliArgs handles call / --args / --args-file / --args-stdin / --list / --schema
• Unit: executeTool returns raw action result; handleToolCall wraps it (regression)
• Unit: getActionInputJsonSchema exposes input schema
• Unit: runCall exits with 2 on unknown tool, malformed JSON, missing tool name
• Unit: runCall exits with 3 on typed tool failure (via vi.doMock stub)
• Unit: formatJsonForOutput pretty-vs-compact based on isTty
• 177/177 tests pass, 194/194 spec coverage
• Smoke-tested live against real Microsoft Graph API:
  • call --list returned all 17 tools
  • call list_emails --schema returned valid JSON Schema
  • call list_emails --args '{"limit":2}' returned live Graph results

[codecov]

Codecov Report

❌ Patch coverage is 73.58491% with 28 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/email-mcp/src/cli.ts	72.00%	20 Missing and 8 partials ⚠️

📢 Thoughts on this report? Let us know!

[stevenobiajulu]

Pushed 553f123 and 09bd482 after a peer-review pass (Codex + Gemini) and end-to-end smoke testing surfaced bugs.

Critical (smoke-test-found): bin discarded exit codes (regression now pinned)
The bin script packages/email-agent-mcp/bin/email-agent-mcp.js called runCli() and only handled thrown errors with process.exit(1) — non-zero return values were silently dropped. email-agent-mcp call no_such_tool returned 0 to the shell despite printing an error. Affected ALL subcommands; call is just where it first matters for piped/scripted use. Fix: route the bin through runCliDirect (now exported), which sets process.exitCode. Regression test added under cli/Direct entrypoint lifecycle.

High (Codex-found): schema validation mapped to exit 3 instead of 2
The catch in runCall was regex-matching error message text — Zod v4's actual message format starts with [\n {\n "expected"... which my regex didn't match, so action.input.parse(...) failures fell through to runtime-failure (exit 3) instead of CLI-error (exit 2). Fix: catch err instanceof z.ZodError explicitly.

Medium (Codex-found): --mailbox silently ignored
call parsed --mailbox but never forwarded it to the tool. Mailbox-sensitive tools route from args.mailbox, not from CLI opts, so call delete_email --mailbox personal --args '{...}' silently targeted the default mailbox. Real correctness risk. Fix: merge opts.mailbox into args.mailbox when not already present (in-args value wins).

Medium (Codex-found): eager init blocked get_mailbox_status
get_mailbox_status is intentionally non-blocking — the diagnostic tool that reports pending/not_configured/error state. My eager-init gate short-circuited it with exit 3 exactly when it would be most useful. Fix: skip ensureProvider when tool name is get_mailbox_status.

Cleanups (Gemini-found):

• Skip WatchedAllowlist for one-shot use — call loadSendAllowlist(path) directly
• Drop redundant await waitForInit(state) after await ensureProvider(state) (ensureProvider awaits init internally)

Verification:

• 181/181 tests pass, 196/196 spec coverage, lint clean
• End-to-end smoke against real Microsoft Graph: 14 distinct scenarios (--list, --schema, --args, --args-file, --args-stdin, jq integration, all four exit codes, regression for non-call commands, full create_draft → update_draft → read_email flow that integrates PR fix(graph): preserve auto-quoted thread history in update_draft #71's quoted-thread fix)