# azizmazrou/ews-mcp architecture

> Architecture diagram of the GitHub repository azizmazrou/ews-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azizmazrou/ews-mcp
- Repository: https://github.com/azizmazrou/ews-mcp

## Overview

The repository’s recommended product is the v5/ewsmcp 4.5 Model Context Protocol server; src/ is the separately maintained legacy 4.0 line. The principal workflow is an MCP client calling a registered mailbox tool, which uses the EWS gateway and returns compact typed results. Major documented branches include mail, calendar/people, tasks, safe writes, semantic search, and server status. The graph emphasizes v5; relationships among tool modules and some internal safety/cache details are based on documentation or source-index references rather than inspected implementation excerpts.

Main entry points: [`v5/ewsmcp/server.py`](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/server.py) (Tool server), [`v5/ewsmcp/tools/base.py`](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/base.py) (Tool dispatch), [`v5/ewsmcp/tools/mail_read.py`](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/mail_read.py) (Mail tools), [`v5/ewsmcp/gateway/client.py`](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/gateway/client.py) (EWS gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_entry["Process entry<br/>[main.py]"]
  node_transport["MCP and HTTP<br/>[http.py]"]
  node_server["Tool server<br/>[server.py]"]
  node_registry["Tool registry<br/>[__init__.py]"]
  node_toolbase["Tool dispatch<br/>[base.py]"]
end

subgraph group_mailbox["Mailbox access"]
  node_gateway["EWS gateway<br/>[client.py]"]
  node_connection["Connection manager<br/>[connection.py]"]
  node_cache[("Local cache<br/>[store.py]")]
  node_sync["Cache synchronization<br/>[sync.py]"]
  node_semantic["Semantic search<br/>[semantic.py]"]
end

subgraph group_capabilities["Assistant capabilities"]
  node_mail["Mail tools<br/>[mail_read.py]"]
  node_calendar["Calendar and people<br/>[calendar_people.py]"]
  node_tasks["Tasks and follow-ups<br/>[tasks.py]"]
  node_writes["Drafts and writes<br/>[writes.py]"]
end

subgraph group_safety["Safety and state"]
  node_aliases["Short ID aliases<br/>[ids.py]"]
  node_confirmation["Send confirmation<br/>[confirm.py]"]
  node_audit["Audit chain<br/>[audit.py]"]
  node_config["Settings and tiers<br/>[config.py]"]
end

node_client(("MCP client"))
node_exchange[("Exchange EWS")]

node_client -->|"starts stdio"| node_entry
node_client -->|"calls HTTP"| node_transport
node_entry -->|"loads"| node_transport
node_entry -->|"starts"| node_server
node_server -->|"creates"| node_gateway
node_server -->|"builds"| node_registry
node_server -->|"starts manager"| node_connection
node_server -->|"initializes"| node_cache
node_server -->|"initializes"| node_semantic
node_server -->|"initializes"| node_audit
node_server -->|"initializes"| node_aliases
node_server -->|"dispatches"| node_toolbase
node_gateway -->|"connects"| node_exchange
node_connection -->|"manages"| node_gateway
node_sync -->|"reads mailbox"| node_gateway
node_sync -->|"updates mirror"| node_cache
node_sync -->|"feeds index"| node_semantic
node_toolbase -->|"dispatches"| node_mail
node_toolbase -->|"dispatches"| node_calendar
node_toolbase -->|"dispatches"| node_tasks
node_toolbase -->|"dispatches"| node_writes
node_writes -->|"confirms send"| node_confirmation
node_server -->|"loads settings"| node_config
node_server -->|"records actions"| node_audit
node_mail -.->|"searches mirror"| node_cache
node_mail -.->|"optionally searches"| node_semantic
node_mail -.->|"uses short IDs"| node_aliases

click node_entry "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/main.py"
click node_transport "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/http.py"
click node_server "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/server.py"
click node_registry "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/__init__.py"
click node_toolbase "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/base.py"
click node_gateway "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/gateway/client.py"
click node_connection "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/gateway/connection.py"
click node_cache "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/cache/store.py"
click node_sync "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/cache/sync.py"
click node_semantic "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/semantic.py"
click node_mail "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/mail_read.py"
click node_calendar "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/calendar_people.py"
click node_tasks "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/tasks.py"
click node_writes "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/writes.py"
click node_aliases "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/ids.py"
click node_confirmation "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/confirm.py"
click node_audit "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/audit.py"
click node_config "https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/config.py"

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_entry,node_transport,node_server,node_registry,node_toolbase,node_client toneBlue
class node_gateway,node_connection,node_cache,node_sync,node_semantic,node_exchange toneAmber
class node_mail,node_calendar,node_tasks,node_writes toneMint
class node_aliases,node_confirmation,node_audit,node_config toneRose
```

## Components

### Server runtime

- [Process entry](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/main.py): `v5/ewsmcp/main.py`
- [MCP and HTTP](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/http.py): `v5/ewsmcp/http.py`
- [Tool server](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/server.py): `v5/ewsmcp/server.py`
- [Tool registry](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/__init__.py): `v5/ewsmcp/tools/__init__.py`
- [Tool dispatch](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/base.py): `v5/ewsmcp/tools/base.py`

### Mailbox access

- [EWS gateway](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/gateway/client.py): `v5/ewsmcp/gateway/client.py`
- [Connection manager](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/gateway/connection.py): `v5/ewsmcp/gateway/connection.py`
- [Local cache](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/cache/store.py): `v5/ewsmcp/cache/store.py`
- [Cache synchronization](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/cache/sync.py): `v5/ewsmcp/cache/sync.py`
- [Semantic search](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/semantic.py): `v5/ewsmcp/semantic.py`

### Assistant capabilities

- [Mail tools](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/mail_read.py): `v5/ewsmcp/tools/mail_read.py`
- [Calendar and people](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/calendar_people.py): `v5/ewsmcp/tools/calendar_people.py`
- [Tasks and follow-ups](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/tasks.py): `v5/ewsmcp/tools/tasks.py`
- [Drafts and writes](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/tools/writes.py): `v5/ewsmcp/tools/writes.py`

### Safety and state

- [Short ID aliases](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/ids.py): `v5/ewsmcp/ids.py`
- [Send confirmation](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/confirm.py): `v5/ewsmcp/confirm.py`
- [Audit chain](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/audit.py): `v5/ewsmcp/audit.py`
- [Settings and tiers](https://github.com/azizmazrou/ews-mcp/blob/main/v5/ewsmcp/config.py): `v5/ewsmcp/config.py`

### Other components

- **MCP client**
- **Exchange EWS**

## Connections

- MCP client → Process entry: starts stdio (evidence: `README.md`)
- MCP client → MCP and HTTP: calls HTTP (evidence: `README.md`)
- Process entry → MCP and HTTP: loads (evidence: `v5/ewsmcp/main.py`)
- Process entry → Tool server: starts (evidence: `v5/ewsmcp/main.py`)
- Tool server → EWS gateway: creates (evidence: `v5/ewsmcp/server.py`)
- Tool server → Tool registry: builds (evidence: `v5/ewsmcp/server.py`)
- Tool server → Connection manager: starts manager (evidence: `v5/ewsmcp/server.py`)
- Tool server → Local cache: initializes (evidence: `v5/ewsmcp/server.py`)
- Tool server → Semantic search: initializes (evidence: `v5/ewsmcp/server.py`)
- Tool server → Audit chain: initializes (evidence: `v5/ewsmcp/server.py`)
- Tool server → Short ID aliases: initializes (evidence: `v5/ewsmcp/server.py`)
- Tool server → Tool dispatch: dispatches (evidence: `v5/ewsmcp/server.py`)
- EWS gateway → Exchange EWS: connects (evidence: `v5/ewsmcp/gateway/client.py`)
- Connection manager → EWS gateway: manages (evidence: `v5/ewsmcp/server.py`)
- Cache synchronization → EWS gateway: reads mailbox
- Cache synchronization → Local cache: updates mirror
- Cache synchronization → Semantic search: feeds index
- Tool dispatch → Mail tools: dispatches (evidence: `README.md`)
- Tool dispatch → Calendar and people: dispatches (evidence: `README.md`)
- Tool dispatch → Tasks and follow-ups: dispatches (evidence: `README.md`)
- Tool dispatch → Drafts and writes: dispatches (evidence: `README.md`)
- Drafts and writes → Send confirmation: confirms send (evidence: `README.md`)
- Tool server → Settings and tiers: loads settings (evidence: `v5/ewsmcp/server.py`)
- Tool server → Audit chain: records actions (evidence: `README.md`)
- Mail tools → Local cache: searches mirror
- Mail tools → Semantic search: optionally searches
- Mail tools → Short ID aliases: uses short IDs
