msteams-mcp: Instructions file for Codex

Agent Guidelines for Teams MCP

This document captures project knowledge to help AI agents work effectively with this codebase.

Repository

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

Project Overview

This is an MCP (Model Context Protocol) server that enables AI assistants to interact with Microsoft Teams. Rather than using the complex Microsoft Graph API, it uses Teams APIs (Substrate, chatsvc, CSA) with authentication tokens extracted from a browser session. The browser is only used for initial login - all operations use direct API calls.

Architecture

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
├── 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 tools
│   └── auth-tools.ts     # Login and status tools
├── auth/                 # Authentication and credential management
│   ├── index.ts          # Module exports
│   ├── 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
│   ├── tmp-auth-tokens.ts # Decrypt New Teams encrypted tmp.auth tokens
│   ├── 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)
│   ├── index.ts          # Module exports
│   ├── 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-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)
│   └── 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)
│   ├── parsers-reactions.ts # Emoji reaction parsing from raw messages
│   ├── http.ts           # HTTP client with retry, timeout, error handling
│   ├── api-config.ts     # API endpoints and header configuration
│   └── 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