msteams-mcp 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob MacDonald
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# Teams MCP Server
+
+[![CI](https://github.com/m0nkmaster/msteams-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/m0nkmaster/msteams-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+
+An MCP (Model Context Protocol) server that enables AI assistants to interact with Microsoft Teams. Search messages, send replies, manage favourites, and more.
+
+## How It Works
+
+This server calls Microsoft's Teams APIs directly (Substrate, chatsvc, CSA)  - the same APIs the Teams web app uses. No Azure AD app registration or admin consent required.
+
+**Authentication flow:**
+1. AI runs `teams_login` to open a browser for you to log in
+2. OAuth tokens are extracted and cached
+3. All operations use cached tokens directly (no browser needed)
+4. Automatic token refresh (~1 hour)
+
+**Security:** Uses the same authentication as the Teams web client - your access is limited to what your account can already do.
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- A Microsoft account with Teams access
+- Google Chrome, Microsoft Edge, or Chromium browser installed
+
+### Setup
+
+Clone and build:
+
+```bash
+git clone https://github.com/m0nkmaster/msteams-mcp.git
+cd teams-mcp-server
+npm install && npm run build
+```
+
+### Configure Your MCP Client
+
+Add to your MCP client configuration (e.g., Claude Desktop, Cursor):
+
+```json
+{
+  "mcpServers": {
+    "teams": {
+      "command": "/path/to/teams-mcp-server/bin/run.sh"
+    }
+  }
+}
+```
+
+Replace `/path/to/teams-mcp-server` with the actual path where you cloned the repo.
+
+The `run.sh` script checks for updates on startup:
+- If remote has new commits, pulls and rebuilds (~5-10s)
+- If already up-to-date, starts immediately (~200ms overhead)
+- If offline, runs the existing build
+
+**Windows users:** Use Git Bash or WSL to run the script, or run directly with `node /path/to/teams-mcp-server/dist/index.js` (manual updates with `git pull && npm install && npm run build`).
+
+The server uses your system's Chrome (macOS/Linux) or Edge (Windows) for authentication.
+
+## Available Tools
+
+### Search & Discovery
+
+| Tool | Description |
+|------|-------------|
+| `teams_search` | Search messages with operators (`from:`, `sent:`, `in:`, `hasattachment:`, etc.) |
+| `teams_get_thread` | Get messages from a conversation/thread |
+| `teams_find_channel` | Find channels by name (your teams + org-wide discovery) |
+| `teams_get_activity` | Get activity feed (mentions, reactions, replies, notifications) |
+
+### Messaging
+
+| Tool | Description |
+|------|-------------|
+| `teams_send_message` | Send a message (default: self-chat/notes). Use `replyToMessageId` for thread replies |
+| `teams_edit_message` | Edit one of your own messages |
+| `teams_delete_message` | Delete one of your own messages (soft delete) |
+
+### People & Contacts
+
+| Tool | Description |
+|------|-------------|
+| `teams_get_me` | Get current user profile (email, name, ID) |
+| `teams_search_people` | Search for people by name or email |
+| `teams_get_frequent_contacts` | Get frequently contacted people (useful for name resolution) |
+| `teams_get_chat` | Get conversation ID for 1:1 chat with a person |
+| `teams_create_group_chat` | Create a new group chat with multiple people (2+ others) |
+
+### Organisation
+
+| Tool | Description |
+|------|-------------|
+| `teams_get_favorites` | Get pinned/favourite conversations |
+| `teams_add_favorite` | Pin a conversation |
+| `teams_remove_favorite` | Unpin a conversation |
+| `teams_save_message` | Bookmark a message |
+| `teams_unsave_message` | Remove bookmark from a message |
+| `teams_get_saved_messages` | Get list of saved/bookmarked messages with source references |
+| `teams_get_followed_threads` | Get list of followed threads with source references |
+| `teams_get_unread` | Get unread counts (aggregate or per-conversation) |
+| `teams_mark_read` | Mark a conversation as read up to a message |
+
+### Reactions
+
+| Tool | Description |
+|------|-------------|
+| `teams_search_emoji` | Search for emojis by name (standard + custom org emojis) |
+| `teams_add_reaction` | Add an emoji reaction to a message |
+| `teams_remove_reaction` | Remove an emoji reaction from a message |
+
+**Quick reactions:** `like`, `heart`, `laugh`, `surprised`, `sad`, `angry` can be used directly without searching.
+
+### Calendar
+
+| Tool | Description |
+|------|-------------|
+| `teams_get_meetings` | Get meetings from calendar (defaults to next 7 days) |
+
+Returns: subject, times, organiser, join URL, `threadId` for meeting chat. Use with `teams_get_thread` to read meeting discussions.
+
+### Session
+
+| Tool | Description |
+|------|-------------|
+| `teams_login` | Trigger manual login (opens browser) |
+| `teams_status` | Check authentication and session state |
+
+### Search Operators
+
+The search supports Teams' native operators:
+
+```
+from:sarah@company.com     # Messages from person
+sent:2026-01-20            # Messages from specific date
+sent:>=2026-01-15          # Messages since date
+in:project-alpha           # Messages in channel
+"Rob Smith"                # Find @mentions (name in quotes)
+hasattachment:true         # Messages with files
+NOT from:email@co.com      # Exclude results
+```
+
+Combine operators: `from:sarah@co.com sent:>=2026-01-18 hasattachment:true`
+
+**Note:** `@me`, `from:me`, `to:me` do NOT work. Use `teams_get_me` first to get your email/displayName. `sent:today` works, but `sent:lastweek` and `sent:thisweek` do NOT - use explicit dates or omit (results are sorted by recency).
+
+## MCP Resources
+
+The server also exposes passive resources for context discovery:
+
+| Resource URI | Description |
+|--------------|-------------|
+| `teams://me/profile` | Current user's profile |
+| `teams://me/favorites` | Pinned conversations |
+| `teams://status` | Authentication status |
+
+## CLI Tools (Development)
+
+For local development, CLI tools are available for testing and debugging:
+
+```bash
+# Check authentication status
+npm run cli -- status
+
+# Search messages
+npm run cli -- search "meeting notes"
+npm run cli -- search "project" --from 0 --size 50
+
+# Send messages (default: your own notes/self-chat)
+npm run cli -- send "Hello from Teams MCP!"
+npm run cli -- send "Message" --to "conversation-id"
+
+# Force login
+npm run cli -- login --force
+
+# Output as JSON
+npm run cli -- search "query" --json
+```
+
+### MCP Test Harness
+
+Test the server through the actual MCP protocol:
+
+```bash
+# List available tools
+npm run test:mcp
+
+# Call any tool
+npm run test:mcp -- search "your query"
+npm run test:mcp -- status
+npm run test:mcp -- people "john smith"
+npm run test:mcp -- favorites
+npm run test:mcp -- activity              # Get activity feed
+npm run test:mcp -- unread                # Check unread counts
+npm run test:mcp -- teams_search_emoji --query "heart"  # Search emojis
+```
+
+## Limitations
+
+- **Login required** - Run `teams_login` to authenticate (opens browser)
+- **Token expiry** - Tokens expire after ~1 hour; headless refresh is attempted or run `teams_login` again when needed
+- **Undocumented APIs** - Uses Microsoft's internal APIs which may change without notice
+- **Search limitations** - Full-text search only; thread replies not matching search terms won't appear (use `teams_get_thread` for full context)
+- **Own messages only** - Edit/delete only works on your own messages
+
+## Session Files
+
+Session files are stored in a user config directory (encrypted):
+
+- **macOS/Linux**: `~/.teams-mcp-server/`
+- **Windows**: `%APPDATA%\teams-mcp-server\`
+
+Contents: `session-state.json`, `token-cache.json`, `.user-data/`
+
+If your session expires, call `teams_login` or delete the config directory.
+
+## Development
+
+For local development:
+
+```bash
+git clone https://github.com/m0nkmaster/msteams-mcp.git
+cd microsoft-teams-mcp
+npm install
+npm run build
+```
+
+Development commands:
+
+```bash
+npm run dev          # Run MCP server in dev mode
+npm run build        # Compile TypeScript
+npm run lint         # Run ESLint
+npm run research     # Explore Teams APIs (logs network calls)
+npm test             # Run unit tests
+npm run typecheck    # TypeScript type checking
+```
+
+For development with hot reload, configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "teams": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/microsoft-teams-mcp/src/index.ts"]
+    }
+  }
+}
+```
+
+See [AGENTS.md](AGENTS.md) for detailed architecture and contribution guidelines.
+
+---
+
+## Teams Chat Export Bookmarklet
+
+This repo also includes a standalone bookmarklet for exporting Teams chat messages to Markdown. See [teams-bookmarklet/README.md](teams-bookmarklet/README.md).

package/dist/__fixtures__/api-responses.d.ts

@@ -0,0 +1,254 @@
+/**
+ * API response fixtures for testing.
+ *
+ * These are based on real API response structures documented in docs/API-REFERENCE.md.
+ * They represent the shape of data returned by Teams/Substrate APIs.
+ */
+/**
+ * Substrate v2 search result item.
+ * From: POST https://substrate.office.com/searchservice/api/v2/query
+ */
+export declare const searchResultItem: {
+    Id: string;
+    ReferenceId: string;
+    HitHighlightedSummary: string;
+    Summary: string;
+    Source: {
+        DateTimeReceived: string;
+        From: {
+            EmailAddress: {
+                Name: string;
+                Address: string;
+            };
+        };
+        ChannelName: string;
+        TeamName: string;
+        Extensions: {
+            SkypeSpaces_ConversationPost_Extension_SkypeGroupId: string;
+        };
+        ClientConversationId: string;
+    };
+};
+/**
+ * Search result with HTML content that needs stripping.
+ */
+export declare const searchResultWithHtml: {
+    Id: string;
+    ReferenceId: string;
+    HitHighlightedSummary: string;
+    Source: {
+        DateTimeReceived: string;
+        From: string;
+        ClientThreadId: string;
+    };
+};
+/**
+ * Minimal search result with only required fields.
+ */
+export declare const searchResultMinimal: {
+    Id: string;
+    HitHighlightedSummary: string;
+};
+/**
+ * Search result too short to be valid (content < 5 chars).
+ */
+export declare const searchResultTooShort: {
+    Id: string;
+    HitHighlightedSummary: string;
+};
+/**
+ * Full EntitySets response structure from v2 query.
+ */
+export declare const searchEntitySetsResponse: {
+    EntitySets: {
+        ResultSets: {
+            Total: number;
+            Results: ({
+                Id: string;
+                ReferenceId: string;
+                HitHighlightedSummary: string;
+                Summary: string;
+                Source: {
+                    DateTimeReceived: string;
+                    From: {
+                        EmailAddress: {
+                            Name: string;
+                            Address: string;
+                        };
+                    };
+                    ChannelName: string;
+                    TeamName: string;
+                    Extensions: {
+                        SkypeSpaces_ConversationPost_Extension_SkypeGroupId: string;
+                    };
+                    ClientConversationId: string;
+                };
+            } | {
+                Id: string;
+                ReferenceId: string;
+                HitHighlightedSummary: string;
+                Source: {
+                    DateTimeReceived: string;
+                    From: string;
+                    ClientThreadId: string;
+                };
+            })[];
+        }[];
+    }[];
+};
+/**
+ * Person suggestion from Substrate suggestions API.
+ * From: POST https://substrate.office.com/search/api/v1/suggestions
+ */
+export declare const personSuggestion: {
+    Id: string;
+    MRI: string;
+    DisplayName: string;
+    GivenName: string;
+    Surname: string;
+    EmailAddresses: string[];
+    CompanyName: string;
+    Department: string;
+    JobTitle: string;
+};
+/**
+ * Person with minimal info using a proper GUID (no optional fields).
+ */
+export declare const personMinimal: {
+    Id: string;
+    DisplayName: string;
+};
+/**
+ * Person with base64-encoded GUID (real-world API response format).
+ * The base64 '93qkaTtFGWpUHjyRafgdhg==' decodes to GUID '69a47af7-453b-6a19-541e-3c9169f81d86'.
+ */
+export declare const personWithBase64Id: {
+    Id: string;
+    MRI: string;
+    DisplayName: string;
+    EmailAddresses: string[];
+};
+/**
+ * Groups response from suggestions API.
+ */
+export declare const peopleGroupsResponse: {
+    Groups: {
+        Suggestions: {
+            Id: string;
+            DisplayName: string;
+        }[];
+    }[];
+};
+/**
+ * JWT payload with full user info.
+ */
+export declare const jwtPayloadFull: {
+    oid: string;
+    name: string;
+    upn: string;
+    preferred_username: string;
+    email: string;
+    given_name: string;
+    family_name: string;
+    tid: string;
+    exp: number;
+    iat: number;
+};
+/**
+ * JWT payload with minimal info (only required fields).
+ */
+export declare const jwtPayloadMinimal: {
+    oid: string;
+    name: string;
+    exp: number;
+};
+/**
+ * JWT payload for name parsing tests - "Surname, GivenName" format.
+ */
+export declare const jwtPayloadCommaName: {
+    oid: string;
+    name: string;
+    upn: string;
+};
+/**
+ * JWT payload for name parsing tests - "GivenName Surname" format.
+ */
+export declare const jwtPayloadSpaceName: {
+    oid: string;
+    name: string;
+    upn: string;
+};
+/**
+ * Channel thread reply - messageid differs from message timestamp.
+ * The parent post was at 1768919400000 (2026-01-20T14:30:00.000Z),
+ * this reply is at 1768921200000 (2026-01-20T15:00:00.000Z).
+ */
+export declare const searchResultThreadReply: {
+    Id: string;
+    ReferenceId: string;
+    HitHighlightedSummary: string;
+    Source: {
+        DateTimeReceived: string;
+        From: {
+            EmailAddress: {
+                Name: string;
+                Address: string;
+            };
+        };
+        ChannelName: string;
+        TeamName: string;
+        Extensions: {
+            SkypeSpaces_ConversationPost_Extension_SkypeGroupId: string;
+        };
+        ClientConversationId: string;
+        ClientThreadId: string;
+    };
+};
+/**
+ * Message source with explicit message ID.
+ */
+export declare const sourceWithMessageId: {
+    MessageId: string;
+    DateTimeReceived: string;
+    ClientConversationId: string;
+};
+/**
+ * Message source with ID in ClientConversationId.
+ */
+export declare const sourceWithConvIdMessageId: {
+    DateTimeReceived: string;
+    ClientConversationId: string;
+};
+/**
+ * Thread message from chatsvc API.
+ * From: GET /api/chatsvc/{region}/v1/users/ME/conversations/{id}/messages
+ */
+export declare const threadMessage: {
+    id: string;
+    content: string;
+    messagetype: string;
+    contenttype: string;
+    from: string;
+    imdisplayname: string;
+    originalarrivaltime: string;
+    composetime: string;
+    clientmessageid: string;
+};
+/**
+ * Favorites folder response.
+ * From: POST /api/csa/{region}/api/v1/teams/users/me/conversationFolders
+ */
+export declare const favoritesFolderResponse: {
+    folderHierarchyVersion: number;
+    conversationFolders: {
+        id: string;
+        sortType: string;
+        name: string;
+        folderType: string;
+        conversationFolderItems: {
+            conversationId: string;
+            createdTime: number;
+            lastUpdatedTime: number;
+        }[];
+    }[];
+};