# softeria/ms-365-mcp-server architecture

> Architecture diagram of the GitHub repository softeria/ms-365-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/softeria/ms-365-mcp-server
- Repository: https://github.com/softeria/ms-365-mcp-server

## Overview

##### Project type and purpose
- This is an open-source Node.js tool that implements a Model Context Protocol (MCP) server and CLI for interacting with Microsoft 365 services via the Graph API.
- It exposes both a command-line interface (login, verify, start server) and a long-running server process that speaks MCP over stdio (or as spawned by clients like Claude).

##### File structure
- bin/ : build-time scripts that fetch OpenAPI specs, generate TypeScript client code, release workflows
- src/ : runtime code
- cli.ts – parses CLI flags and entry point
- server.ts – instantiates and runs the MCP server
- auth-tools.ts and auth.ts – encapsulate MSAL device-code flow and token caching
- graph-client.ts / graph-tools.ts – wrapper around the generated Graph client
- generated/ – OpenAPI-derived client and endpoint types
- logger.ts – centralized logging abstraction
- package.json, workflows – CI/CD and npm publish configuration
- test/ – unit tests for each subsystem

##### Reading the README
- Confirms that authentication uses MSAL with device-code flow and token cache in OS credential store (fallback to file).
- Describes CLI flags (`--login`, `--verify-login`, server flags like `--read-only`).
- Integration points: spawned by other MCP-aware applications.

##### Main components
a. User / Client:
- **CLI client** invoking `npx @softeria/ms-365-mcp-server [flags]`
- **MCP-aware host** (e.g., Claude Desktop) that spawns the server as a subprocess
b. Runtime components:
- **CLI Parser** (cli.ts)
- **Auth Service** (auth.ts + auth-tools.ts) with token cache (OS store / file)
- **Graph Client** (generated client + graph-tools.ts)
- **MCP Server** (server.ts) exposing tool methods over stdio (login, Graph calls, etc.)
- **Logger** (logger.ts)
c. External systems:
- **Microsoft Graph API** (external REST endpoints)
- **OS Credential Store** or local file for token caching
d. Build-time components (optional, side by side):
- **OpenAPI fetcher** and **code generator** (bin/modules/download-openapi.mjs + generate-graph-client.mjs)

##### Relationships and interactions
- CLI Parser → decides: if `--login`, route to Auth Service → device code flow → OS Credential Store
- On normal startup: CLI Parser → starts MCP Server → listens on stdio
- MCP Server receives commands from host → dispatches to Auth Service or Graph Client
- Graph Client calls Microsoft Graph API over HTTPS
- Logger records all activity, respects `LOG_LEVEL` and `SILENT` flags
- Build-time scripts run once to refresh generated client before publishing

##### Architectural patterns and principles
- Separation of concerns: build-time code generation vs. runtime logic; CLI vs. server; auth vs. API calls
- Adapter pattern: graph-tools + generated client adapt raw OpenAPI into friendly methods
- Modular design: each feature (Mail, OneDrive, Excel, etc.) is a tool on the MCP interface
- Configuration via flags and environment variables (12-factor style)

##### Diagramming recommendations
- CLI Parser → Auth Service (login)
- MCP Server ↔ Host (stdio messages)
- MCP Server → Graph Client → Graph API
- Auth Service → OS Credential Store
- Blue for internal services (Auth, Graph client)
- Green for external systems (Graph API, Credential store)
- Gray for entry points (CLI, MCP Server)
- Clouds for external APIs
- Rectangles for modules

##### Essentials
- Component names exactly as in source (cli.ts, auth-tools.ts, server.ts, etc.)
- Data flows for authentication, command dispatch, and HTTP calls
- Config flags and environment variables that alter behavior
- Distinction between build-time code generation and runtime operation

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Layer 1: User/Host"
        CLI["CLI Client (npx @softeria/ms-365-mcp-server)"]:::external
        Host["MCP-aware Host"]:::external
    end

    subgraph "Layer 2: Entry Points"
        CLIParser["cli.ts"]:::entry
        MCPServer["server.ts"]:::entry
        Index["index.ts"]:::entry
        Version["version.ts"]:::entry
    end

    subgraph "Layer 3: Core Services"
        subgraph "Auth Service"
            Auth["auth.ts"]:::service
            AuthTools["auth-tools.ts"]:::service
        end
        subgraph "Graph Client"
            GCWrapper["graph-client.ts"]:::service
            GCTools["graph-tools.ts"]:::service
            subgraph "Generated Client"
                GCGen["client.ts"]:::service
                GCEndpoint["endpoint-types.ts"]:::service
                GCHack["hack.ts"]:::service
            end
        end
        Logger["logger.ts"]:::service
    end

    subgraph "Layer 4: External Dependencies"
        GraphAPI["Microsoft Graph API"]:::external
        CredentialStore["OS Credential Store / File"]:::external
    end

    subgraph "Build-time Components"
        OAPI["download-openapi.mjs"]:::build
        CodeGen["generate-graph-client.mjs"]:::build
        MCPGen["generate-mcp-tools.mjs"]:::build
        DescExt["extract-descriptions.mjs"]:::build
        OAPISimp["simplified-openapi.mjs"]:::build
        Release["release.mjs"]:::build
    end

    CLI --> CLIParser
    Host --> MCPServer
    CLIParser -->|"if login"| Auth
    Auth --> CredentialStore
    CLIParser -->|"start server"| MCPServer
    CLIParser --> Logger
    MCPServer --> Auth
    MCPServer --> GCWrapper
    MCPServer --> Logger
    Auth --> AuthTools
    GCWrapper --> GCTools
    GCTools --> GCGen
    GCTools --> GCEndpoint
    GCTools --> GCHack
    GCWrapper --> GraphAPI
    GCWrapper --> Logger
    OAPI --> CodeGen
    CodeGen --> GCGen
    MCPGen --> MCPServer

    click CLIParser "https://github.com/softeria/ms-365-mcp-server/blob/main/src/cli.ts"
    click MCPServer "https://github.com/softeria/ms-365-mcp-server/blob/main/src/server.ts"
    click Auth "https://github.com/softeria/ms-365-mcp-server/blob/main/src/auth.ts"
    click AuthTools "https://github.com/softeria/ms-365-mcp-server/blob/main/src/auth-tools.ts"
    click GCGen "https://github.com/softeria/ms-365-mcp-server/blob/main/src/generated/client.ts"
    click GCEndpoint "https://github.com/softeria/ms-365-mcp-server/blob/main/src/generated/endpoint-types.ts"
    click GCHack "https://github.com/softeria/ms-365-mcp-server/blob/main/src/generated/hack.ts"
    click GCWrapper "https://github.com/softeria/ms-365-mcp-server/blob/main/src/graph-client.ts"
    click GCTools "https://github.com/softeria/ms-365-mcp-server/blob/main/src/graph-tools.ts"
    click Logger "https://github.com/softeria/ms-365-mcp-server/blob/main/src/logger.ts"
    click Index "https://github.com/softeria/ms-365-mcp-server/blob/main/src/index.ts"
    click Version "https://github.com/softeria/ms-365-mcp-server/blob/main/src/version.ts"
    click OAPI "https://github.com/softeria/ms-365-mcp-server/blob/main/bin/modules/download-openapi.mjs"
    click CodeGen "https://github.com/softeria/ms-365-mcp-server/blob/main/bin/generate-graph-client.mjs"
    click MCPGen "https://github.com/softeria/ms-365-mcp-server/blob/main/bin/modules/generate-mcp-tools.mjs"
    click DescExt "https://github.com/softeria/ms-365-mcp-server/blob/main/bin/modules/extract-descriptions.mjs"
    click OAPISimp "https://github.com/softeria/ms-365-mcp-server/blob/main/bin/modules/simplified-openapi.mjs"
    click Release "https://github.com/softeria/ms-365-mcp-server/blob/main/bin/release.mjs"

    classDef entry fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef service fill:#87CEFA,stroke:#333,stroke-width:1px;
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef build fill:#FFA500,stroke:#333,stroke-width:1px;
```
