m365-mcp: Instructions file for Claude Code

CLAUDE.md

Project Overview

Standalone MCP server for Microsoft 365 via the Microsoft Graph API. Provides read-only tools for profile, calendar, mail, Teams chat, OneDrive files, and meeting transcripts. Any MCP client can use it.

Package: @masonator/m365-mcp

Commands

npm install          # Install dependencies
npm run build        # Compile TypeScript (tsc)
npm test             # Run unit tests (jest, 80% coverage threshold)
npm run lint         # Run ESLint
npm run format       # Format with Prettier

Architecture

src/
├── index.ts              # MCP server entry point (stdio transport, tool dispatch)
├── types/
│   └── tokens.ts         # TokenData, AuthConfig interfaces
├── lib/
│   ├── auth.ts           # OAuth2 confidential client, token storage, refresh
│   ├── version.ts        # single source of truth for the version (package.json)
│   ├── format.ts        # shared timestamp/truncation/untrusted-content formatting
│   ├── graph.ts          # graphFetch() wrapper with error mapping
│   └── tools/
│       ├── index.ts        # TOOL_DEFINITIONS — the single source of truth for the roster
│       ├── auth-status.ts  # ms_auth_status — connection check + re-auth
│       ├── profile.ts      # ms_profile — /me
│       ├── calendar.ts     # ms_calendar — /me/calendarView
│       ├── mail.ts         # ms_mail — /me/messages
│       ├── chat.ts         # ms_chat — /me/chats
│       ├── files.ts        # ms_files — /me/drive
│       ├── sharepoint.ts   # ms_sharepoint — /sites
│       ├── schedule.ts     # ms_schedule — /me/calendar/getSchedule
│       ├── teams.ts        # ms_teams — /me/joinedTeams → channels → messages
│       ├── tasks.ts        # ms_tasks — /me/todo, /me/planner/tasks
│       ├── people.ts       # ms_people — /users, /me/memberOf
│       ├── search.ts       # ms_search — /search/query across M365
│       ├── insights.ts     # ms_insights — /me/insights/{used,shared,trending}
│       ├── brief.ts        # ms_brief — composes the tools above, no Graph calls
│       ├── server-info.ts  # ms_server_info — version + registered tools
│       └── transcripts.ts  # ms_transcripts — calendar → meeting ID → VTT
└── __tests__/            # Jest tests (410 tests, ~96% coverage)