How softeria/ms-365-mcp-server works
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