msteams-mcp: Instructions file for Codex

Agent Guidelines for Teams MCP

Non-obvious project knowledge for AI agents. This is not a tool reference: tool parameters and usage live in the tool definitions (src/tools/*.ts), which are the source of truth and are sent to AI assistants via MCP.

Repository

• Repository: https://github.com/m0nkmaster/msteams-mcp
• Install: npx -y msteams-mcp@latest, or clone, npm install && npm run build, then point your MCP client at dist/index.js

Project Overview

An MCP (Model Context Protocol) server that lets AI assistants interact with Microsoft Teams. Instead of the Microsoft Graph API, it calls Teams' own APIs (Substrate, chatsvc, CSA) using tokens extracted from a browser session. The browser is only used for initial login; all operations are direct API calls.

Directory Structure

src/
├── index.ts              # Entry point, runs the MCP server
├── cli.ts                # Standalone CLI (msteams bin) - full tool parity via in-memory MCP transport
├── cli/                  # CLI plumbing, all driven by the tool definitions
│   ├── resolve.ts        # Command resolution and schema-driven flag parsing
│   ├── render.ts         # Generic response rendering, colour/TTY handling
│   └── help.ts           # Generated command index and per-command help
├── server.ts             # MCP server (TeamsServer class) - delegates to tool registry
├── constants.ts          # Shared constants (page sizes, timeouts, thresholds)
├── tools/                # Tool handlers (modular design)
│   ├── index.ts          # Tool context and type definitions
│   ├── registry.ts       # Tool registry - maps names to handlers
│   ├── search-tools.ts   # Search and channel tools
│   ├── message-tools.ts  # Messaging, favourites, save/unsave tools
│   ├── people-tools.ts   # People search and profile tools
│   ├── meeting-tools.ts  # Calendar and meeting tools
│   ├── file-tools.ts     # Shared files and file download tools
│   ├── tag-tools.ts      # Channel tag tools
│   ├── assignment-tools.ts # EDU Assignments tools (list, get with attachments, submission actions)
│   └── auth-tools.ts     # Login and status tools
├── auth/                 # Authentication and credential management
│   ├── crypto.ts         # AES-256-GCM encryption for credentials at rest
│   ├── session-store.ts  # Secure session state storage with encryption
│   ├── token-extractor.ts # Extract tokens from Playwright session state
│   ├── token-refresh.ts  # Token refresh orchestrator (HTTP-first, browser fallback)
│   └── token-refresh-http.ts # Browserless token refresh via direct OAuth2 calls
├── api/                  # API client modules (one per API surface)
│   ├── substrate-api.ts  # Search and people APIs (Substrate v2)
│   ├── chatsvc-api.ts    # Barrel file re-exporting all chatsvc sub-modules
│   ├── chatsvc-common.ts # Shared utilities (date formatting)
│   ├── chatsvc-messaging.ts # Send, edit, delete, threads, 1:1/group chat
│   ├── chatsvc-conversations.ts # Recent conversation list with last-message preview
│   ├── chatsvc-activity.ts  # Activity feed (mentions, reactions, replies)
│   ├── chatsvc-reactions.ts # Add/remove emoji reactions
│   ├── chatsvc-virtual.ts   # Saved messages, followed threads, save/unsave
│   ├── chatsvc-readstatus.ts # Consumption horizons, mark as read, unread
│   ├── csa-api.ts        # Favorites API (CSA)
│   ├── calendar-api.ts   # Calendar/meetings API
│   ├── transcript-api.ts # Meeting transcripts (Substrate WorkingSetFiles)
│   ├── files-api.ts      # Shared files (Substrate AllFiles)
│   ├── tags-api.ts       # Channel tags (mt/part teams/{groupId}/tags)
│   ├── assignments-api.ts # EDU Assignments (assignments.edu.cloud.microsoft, OneNote EDU)
│   ├── graph-files-api.ts # File downloads via Microsoft Graph (shared files and assignment attachments)
│   └── profile-api.ts    # Resolve MRIs to profiles (middleTier fetchShortProfile)
├── browser/              # Playwright browser automation (login only)
│   ├── context.ts        # Persistent browser profile management
│   └── auth.ts           # Authentication detection and manual login handling
├── utils/
│   ├── parsers.ts        # Pure parsing functions (barrel; testable submodules)
│   ├── parsers-*.ts      # Parser submodules (html, markdown, search, people, channels, identifiers, reactions, virtual)
│   ├── http.ts           # HTTP client with retry, timeout, error handling
│   ├── api-config.ts     # API endpoints and header configuration
│   ├── logger.ts         # Prefixed logger used for all production logging
│   └── auth-guards.ts    # Reusable auth check utilities (Result types)
├── types/
│   ├── teams.ts          # Teams data interfaces
│   ├── errors.ts         # Error taxonomy with machine-readable codes
│   ├── result.ts         # Result<T, E> type for explicit error handling
│   └── api-responses.ts  # Typed interfaces for raw API response shapes
├── __fixtures__/
│   └── api-responses.ts  # Mock API responses for testing