# spenserhale/outlook-ai-toolkit architecture

> Architecture diagram of the GitHub repository spenserhale/outlook-ai-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spenserhale/outlook-ai-toolkit
- Repository: https://github.com/spenserhale/outlook-ai-toolkit

## Overview

Outlook Toolkit exposes Outlook mail and account management through a CLI and an MCP server, backed by a shared SDK for Microsoft Graph. The primary flow is CLI sign-in (including profile/config resolution) followed by mail commands, which use SDK mail operations and Graph requests. The MCP server separately registers authentication, mail, and inbox-rule tools. The graph preserves documented sync, body formatting, and bulk-move capabilities; some CLI-to-SDK internals and storage wiring are not shown in the sampled excerpts, so those links are omitted or identified as documented.

Main entry points: [`packages/cli/src/app.ts`](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/app.ts) (CLI routes), [`packages/cli/src/commands/session.ts`](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/commands/session.ts) (Sign-in session), [`packages/sdk/src/mail-client.ts`](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/mail-client.ts) (Mail operations), [`packages/sdk/src/auth.ts`](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/auth.ts) (OAuth and status)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_app["CLI routes<br/>[app.ts]"]
  node_cli_session["Sign-in session<br/>[session.ts]"]
  node_cli_context["Account context<br/>[context.ts]"]
  node_cli_profiles["Profile commands<br/>[profile.ts]"]
  node_cli_mail["Mail commands<br/>[mail.ts]"]
  node_cli_agent["Agent schema<br/>[agent-context.ts]"]
end

subgraph group_sdk["SDK"]
  node_sdk_config["Config resolution<br/>[config.ts]"]
  node_sdk_auth["OAuth and status<br/>[auth.ts]"]
  node_sdk_tokens["Token storage<br/>[token-store.ts]"]
  node_sdk_profiles["Profile storage<br/>[profile-store.ts]"]
  node_sdk_mail["Mail operations<br/>[mail-client.ts]"]
  node_sdk_sweep["Sweep queries<br/>[sweep-query.ts]"]
  node_sdk_rules["Inbox rules<br/>[rules-client.ts]"]
  node_sdk_graph["Graph transport<br/>[graph-client.ts]"]
  node_sdk_body["Body conversion<br/>[body.ts]"]
  node_sdk_format["Output formatting<br/>[format.ts]"]
  node_sdk_types["Domain schemas<br/>[types.ts]"]
end

subgraph group_mcp["MCP Server"]
  node_mcp_server["MCP tool server<br/>[server.ts]"]
  node_mcp_auth["Auth tools<br/>[auth.ts]"]
  node_mcp_mail["Mail tools<br/>[mail.ts]"]
  node_mcp_rules["Rule tools<br/>[rules.ts]"]
end

subgraph group_external["External Services"]
  node_ms_identity["Microsoft identity"]
  node_ms_graph["Microsoft Graph"]
  node_os_keychain[("OS credential store")]
end

node_user(("User or agent"))

node_user -->|"runs commands"| node_cli_app
node_cli_app -->|"routes to"| node_cli_session
node_cli_app -->|"routes to"| node_cli_mail
node_cli_app -->|"routes to"| node_cli_profiles
node_cli_app -->|"routes to"| node_cli_agent
node_cli_session -->|"resolves account"| node_cli_context
node_cli_session -->|"starts sign-in"| node_sdk_auth
node_cli_session -->|"creates store"| node_sdk_tokens
node_cli_profiles -->|"manages profiles"| node_sdk_profiles
node_cli_profiles -->|"starts sign-in"| node_cli_session
node_cli_context -->|"resolves config"| node_sdk_config
node_cli_mail -->|"uses SDK mail"| node_sdk_mail
node_mcp_server -->|"registers"| node_mcp_auth
node_mcp_server -->|"registers"| node_mcp_mail
node_mcp_server -->|"registers"| node_mcp_rules
node_mcp_auth -->|"uses authentication"| node_sdk_auth
node_mcp_mail -->|"uses mail SDK"| node_sdk_mail
node_mcp_rules -->|"uses rules SDK"| node_sdk_rules
node_sdk_auth -->|"uses settings"| node_sdk_config
node_sdk_auth -.->|"authenticates with"| node_ms_identity
node_sdk_tokens -.->|"stores tokens"| node_os_keychain
node_sdk_mail -->|"requests mail data"| node_sdk_graph
node_sdk_mail -->|"converts bodies"| node_sdk_body
node_sdk_mail -->|"builds sweep queries"| node_sdk_sweep
node_sdk_rules -->|"requests rule data"| node_sdk_graph
node_sdk_graph -->|"sends Graph requests"| node_ms_graph

click node_cli_app "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/app.ts"
click node_cli_session "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/commands/session.ts"
click node_cli_context "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/context.ts"
click node_cli_profiles "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/commands/profile.ts"
click node_cli_mail "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/commands/mail.ts"
click node_cli_agent "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/commands/agent-context.ts"
click node_mcp_server "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/mcp/src/server.ts"
click node_mcp_auth "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/mcp/src/tools/auth.ts"
click node_mcp_mail "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/mcp/src/tools/mail.ts"
click node_mcp_rules "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/mcp/src/tools/rules.ts"
click node_sdk_config "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/config.ts"
click node_sdk_auth "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/auth.ts"
click node_sdk_tokens "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/token-store.ts"
click node_sdk_profiles "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/profile-store.ts"
click node_sdk_mail "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/mail-client.ts"
click node_sdk_sweep "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/sweep-query.ts"
click node_sdk_rules "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/rules-client.ts"
click node_sdk_graph "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/graph-client.ts"
click node_sdk_body "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/body.ts"
click node_sdk_format "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/format.ts"
click node_sdk_types "https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/types.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_app,node_cli_session,node_cli_context,node_cli_profiles,node_cli_mail,node_cli_agent,node_user toneBlue
class node_sdk_config,node_sdk_auth,node_sdk_tokens,node_sdk_profiles,node_sdk_mail,node_sdk_sweep,node_sdk_rules,node_sdk_graph,node_sdk_body,node_sdk_format,node_sdk_types toneAmber
class node_mcp_server,node_mcp_auth,node_mcp_mail,node_mcp_rules toneMint
class node_ms_identity,node_ms_graph,node_os_keychain toneRose
```

## Components

### CLI

- [CLI routes](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/app.ts): `packages/cli/src/app.ts`
- [Sign-in session](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/commands/session.ts): `packages/cli/src/commands/session.ts`
- [Account context](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/context.ts): `packages/cli/src/context.ts`
- [Profile commands](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/commands/profile.ts): `packages/cli/src/commands/profile.ts`
- [Mail commands](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/commands/mail.ts): `packages/cli/src/commands/mail.ts`
- [Agent schema](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/cli/src/commands/agent-context.ts): `packages/cli/src/commands/agent-context.ts`

### SDK

- [Config resolution](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/config.ts): `packages/sdk/src/config.ts`
- [OAuth and status](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/auth.ts): `packages/sdk/src/auth.ts`
- [Token storage](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/token-store.ts): `packages/sdk/src/token-store.ts`
- [Profile storage](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/profile-store.ts): `packages/sdk/src/profile-store.ts`
- [Mail operations](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/mail-client.ts): `packages/sdk/src/mail-client.ts`
- [Sweep queries](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/sweep-query.ts): `packages/sdk/src/sweep-query.ts`
- [Inbox rules](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/rules-client.ts): `packages/sdk/src/rules-client.ts`
- [Graph transport](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/graph-client.ts): `packages/sdk/src/graph-client.ts`
- [Body conversion](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/body.ts): `packages/sdk/src/body.ts`
- [Output formatting](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/format.ts): `packages/sdk/src/format.ts`
- [Domain schemas](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/sdk/src/types.ts): `packages/sdk/src/types.ts`

### MCP Server

- [MCP tool server](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/mcp/src/server.ts): `packages/mcp/src/server.ts`
- [Auth tools](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/mcp/src/tools/auth.ts): `packages/mcp/src/tools/auth.ts`
- [Mail tools](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/mcp/src/tools/mail.ts): `packages/mcp/src/tools/mail.ts`
- [Rule tools](https://github.com/spenserhale/outlook-ai-toolkit/blob/main/packages/mcp/src/tools/rules.ts): `packages/mcp/src/tools/rules.ts`

### External Services

- **Microsoft identity**
- **Microsoft Graph**
- **OS credential store**

### Other components

- **User or agent**

## Connections

- User or agent → CLI routes: runs commands (evidence: `README.md`)
- CLI routes → Sign-in session: routes to (evidence: `packages/cli/src/app.ts`)
- CLI routes → Mail commands: routes to (evidence: `packages/cli/src/app.ts`)
- CLI routes → Profile commands: routes to (evidence: `packages/cli/src/app.ts`)
- CLI routes → Agent schema: routes to (evidence: `packages/cli/src/app.ts`)
- Sign-in session → Account context: resolves account (evidence: `packages/cli/src/commands/session.ts`)
- Sign-in session → OAuth and status: starts sign-in (evidence: `packages/cli/src/commands/session.ts`)
- Sign-in session → Token storage: creates store (evidence: `packages/cli/src/commands/session.ts`)
- Profile commands → Profile storage: manages profiles (evidence: `packages/cli/src/commands/profile.ts`)
- Profile commands → Sign-in session: starts sign-in (evidence: `packages/cli/src/commands/profile.ts`)
- Account context → Config resolution: resolves config (evidence: `packages/cli/src/context.ts`)
- Mail commands → Mail operations: uses SDK mail (evidence: `README.md`)
- MCP tool server → Auth tools: registers (evidence: `packages/mcp/src/server.ts`)
- MCP tool server → Mail tools: registers (evidence: `packages/mcp/src/server.ts`)
- MCP tool server → Rule tools: registers (evidence: `packages/mcp/src/server.ts`)
- Auth tools → OAuth and status: uses authentication (evidence: `packages/mcp/src/tools/auth.ts`)
- Mail tools → Mail operations: uses mail SDK (evidence: `packages/mcp/src/tools/mail.ts`)
- Rule tools → Inbox rules: uses rules SDK (evidence: `packages/mcp/src/tools/rules.ts`)
- OAuth and status → Config resolution: uses settings (evidence: `packages/sdk/src/auth.ts`)
- OAuth and status → Microsoft identity: authenticates with
- Token storage → OS credential store: stores tokens (evidence: `README.md`)
- Mail operations → Graph transport: requests mail data (evidence: `packages/sdk/src/mail-client.ts`)
- Mail operations → Body conversion: converts bodies (evidence: `packages/sdk/src/mail-client.ts`)
- Mail operations → Sweep queries: builds sweep queries (evidence: `packages/sdk/src/mail-client.ts`)
- Inbox rules → Graph transport: requests rule data (evidence: `packages/sdk/src/rules-client.ts`)
- Graph transport → Microsoft Graph: sends Graph requests (evidence: `packages/sdk/src/graph-client.ts`)
