msteams-mcp 0.2.0

package/README.md

@@ -0,0 +1,229 @@
+# Teams MCP Server
+
+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 internal 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. Run `teams_login` to open a browser and log in
+2. OAuth tokens are extracted and cached
+3. All operations use cached tokens directly (no browser needed)
+4. When tokens expire (~1 hour), run `teams_login` again
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- A Microsoft account with Teams access
+- Google Chrome, Microsoft Edge, or Chromium browser installed
+
+### Configure Your MCP Client
+
+Add to your MCP client configuration (e.g., Claude Desktop, Cursor):
+
+```json
+{
+  "mcpServers": {
+    "teams": {
+      "command": "npx",
+      "args": ["-y", "msteams-mcp"]
+    }
+  }
+}
+```
+
+That's it. The server uses your system's Chrome (macOS/Linux) or Edge (Windows) for authentication.
+
+### Manual Installation (optional)
+
+If you prefer to install globally:
+
+```bash
+npm install -g msteams-mcp
+```
+
+Then configure:
+
+```json
+{
+  "mcpServers": {
+    "teams": {
+      "command": "msteams-mcp"
+    }
+  }
+}
+```
+
+## 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) |
+
+### Messaging
+
+| Tool | Description |
+|------|-------------|
+| `teams_send_message` | Send a message (default: self-chat/notes) |
+| `teams_reply_to_thread` | Reply to a channel message as a threaded reply |
+| `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 |
+
+### 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 |
+
+### 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:today                 # Messages from today
+sent:lastweek              # Messages from last week
+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:lastweek hasattachment:true`
+
+**Note:** `@me`, `from:me`, `to:me` do NOT work. Use `teams_get_me` first to get your email/displayName, then use those values.
+
+## 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
+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
+```
+
+## Limitations
+
+- **Login required** - Run `teams_login` to authenticate (opens browser)
+- **Token expiry** - Tokens expire after ~1 hour; 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
+
+These files are created locally and gitignored:
+
+- `session-state.json` - Encrypted browser session
+- `token-cache.json` - Encrypted OAuth tokens
+- `.user-data/` - Browser profile
+
+If your session expires, call `teams_login` or delete these files.
+
+## Development
+
+For local development:
+
+```bash
+git clone https://github.com/m0nkmaster/microsoft-teams-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 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,228 @@
+/**
+ * API response fixtures for testing.
+ *
+ * These are based on real API response structures documented in docs/API-RESEARCH.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: {
+        ReceivedTime: 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: {
+        ReceivedTime: 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: {
+                    ReceivedTime: 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: {
+                    ReceivedTime: 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;
+};
+/**
+ * Message source with explicit message ID.
+ */
+export declare const sourceWithMessageId: {
+    MessageId: string;
+    ReceivedTime: string;
+    ClientConversationId: string;
+};
+/**
+ * Message source with ID in ClientConversationId.
+ */
+export declare const sourceWithConvIdMessageId: {
+    ReceivedTime: 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;
+        }[];
+    }[];
+};

package/dist/__fixtures__/api-responses.js

@@ -0,0 +1,217 @@
+/**
+ * API response fixtures for testing.
+ *
+ * These are based on real API response structures documented in docs/API-RESEARCH.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 const searchResultItem = {
+    Id: 'AAMkAGE1OWFlZjc0LWYxMjQtNGM1Mi05NzJlLTU0MTU2ZGU1OGM1YQBGAAAAAACaT2h4EH4ZT5pQgKA-example',
+    ReferenceId: 'abc123-def456.1000.1',
+    HitHighlightedSummary: 'Let me check the <c0>budget</c0> report for Q3',
+    Summary: 'Let me check the budget report for Q3',
+    Source: {
+        ReceivedTime: '2026-01-20T14:30:00.000Z',
+        From: {
+            EmailAddress: {
+                Name: 'Smith, John',
+                Address: 'john.smith@company.com',
+            },
+        },
+        ChannelName: 'General',
+        TeamName: 'Finance Team',
+        Extensions: {
+            SkypeSpaces_ConversationPost_Extension_SkypeGroupId: '19:abcdef123456@thread.tacv2',
+        },
+        ClientConversationId: '19:abcdef123456@thread.tacv2;messageid=1705760000000',
+    },
+};
+/**
+ * Search result with HTML content that needs stripping.
+ */
+export const searchResultWithHtml = {
+    Id: 'AAMkBGFiY2RlZg',
+    ReferenceId: 'xyz789.1000.1',
+    HitHighlightedSummary: '<p>Meeting <strong>notes</strong> from &amp; yesterday&apos;s call</p><br/><div>Action items:</div>',
+    Source: {
+        ReceivedTime: '2026-01-21T09:00:00.000Z',
+        From: 'Jane Doe',
+        ClientThreadId: '19:meeting123@thread.v2',
+    },
+};
+/**
+ * Minimal search result with only required fields.
+ */
+export const searchResultMinimal = {
+    Id: 'minimal-id',
+    HitHighlightedSummary: 'A short message here',
+};
+/**
+ * Search result too short to be valid (content < 5 chars).
+ */
+export const searchResultTooShort = {
+    Id: 'short-id',
+    HitHighlightedSummary: 'Hi',
+};
+/**
+ * Full EntitySets response structure from v2 query.
+ */
+export const searchEntitySetsResponse = {
+    EntitySets: [
+        {
+            ResultSets: [
+                {
+                    Total: 4307,
+                    Results: [
+                        searchResultItem,
+                        searchResultWithHtml,
+                    ],
+                },
+            ],
+        },
+    ],
+};
+/**
+ * Person suggestion from Substrate suggestions API.
+ * From: POST https://substrate.office.com/search/api/v1/suggestions
+ */
+export const personSuggestion = {
+    Id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890@company.onmicrosoft.com',
+    MRI: '8:orgid:a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+    DisplayName: 'Smith, John',
+    GivenName: 'John',
+    Surname: 'Smith',
+    EmailAddresses: ['john.smith@company.com'],
+    CompanyName: 'Acme Corp',
+    Department: 'Engineering',
+    JobTitle: 'Senior Engineer',
+};
+/**
+ * Person with minimal info using a proper GUID (no optional fields).
+ */
+export const personMinimal = {
+    Id: 'b1c2d3e4-f5a6-7890-bcde-1234567890ab',
+    DisplayName: 'Jane Doe',
+};
+/**
+ * Person with base64-encoded GUID (real-world API response format).
+ * The base64 '93qkaTtFGWpUHjyRafgdhg==' decodes to GUID '69a47af7-453b-6a19-541e-3c9169f81d86'.
+ */
+export const personWithBase64Id = {
+    Id: '93qkaTtFGWpUHjyRafgdhg==',
+    MRI: '8:orgid:93qkaTtFGWpUHjyRafgdhg==',
+    DisplayName: 'Rob MacDonald',
+    EmailAddresses: ['rob@company.com'],
+};
+/**
+ * Groups response from suggestions API.
+ */
+export const peopleGroupsResponse = {
+    Groups: [
+        {
+            Suggestions: [
+                personSuggestion,
+                personMinimal,
+            ],
+        },
+    ],
+};
+/**
+ * JWT payload with full user info.
+ */
+export const jwtPayloadFull = {
+    oid: 'user-object-id-guid',
+    name: 'Macdonald, Rob',
+    upn: 'rob.macdonald@company.com',
+    preferred_username: 'rob@company.com',
+    email: 'rob.m@personal.com',
+    given_name: 'Rob',
+    family_name: 'Macdonald',
+    tid: 'tenant-id-guid',
+    exp: 1705850000,
+    iat: 1705846400,
+};
+/**
+ * JWT payload with minimal info (only required fields).
+ */
+export const jwtPayloadMinimal = {
+    oid: 'another-user-guid',
+    name: 'Alice Smith',
+    exp: 1705850000,
+};
+/**
+ * JWT payload for name parsing tests - "Surname, GivenName" format.
+ */
+export const jwtPayloadCommaName = {
+    oid: 'comma-name-user',
+    name: 'Jones, David',
+    upn: 'david.jones@company.com',
+};
+/**
+ * JWT payload for name parsing tests - "GivenName Surname" format.
+ */
+export const jwtPayloadSpaceName = {
+    oid: 'space-name-user',
+    name: 'Sarah Connor',
+    upn: 'sarah.connor@company.com',
+};
+/**
+ * Message source with explicit message ID.
+ */
+export const sourceWithMessageId = {
+    MessageId: '1705760000000',
+    ReceivedTime: '2026-01-20T12:00:00.000Z',
+    ClientConversationId: '19:thread@tacv2',
+};
+/**
+ * Message source with ID in ClientConversationId.
+ */
+export const sourceWithConvIdMessageId = {
+    ReceivedTime: '2026-01-20T12:00:00.000Z',
+    ClientConversationId: '19:thread@tacv2;messageid=1705770000000',
+};
+/**
+ * Thread message from chatsvc API.
+ * From: GET /api/chatsvc/{region}/v1/users/ME/conversations/{id}/messages
+ */
+export const threadMessage = {
+    id: '1705760000000',
+    content: '<p>Hello team!</p>',
+    messagetype: 'RichText/Html',
+    contenttype: 'text',
+    from: '8:orgid:user-guid-123',
+    imdisplayname: 'John Smith',
+    originalarrivaltime: '2026-01-20T12:00:00.000Z',
+    composetime: '2026-01-20T11:59:58.000Z',
+    clientmessageid: 'client-msg-123',
+};
+/**
+ * Favorites folder response.
+ * From: POST /api/csa/{region}/api/v1/teams/users/me/conversationFolders
+ */
+export const favoritesFolderResponse = {
+    folderHierarchyVersion: 1705850000000,
+    conversationFolders: [
+        {
+            id: 'tenant-guid~user-guid~Favorites',
+            sortType: 'UserDefinedCustomOrder',
+            name: 'Favorites',
+            folderType: 'Favorites',
+            conversationFolderItems: [
+                {
+                    conversationId: '19:abc@thread.tacv2',
+                    createdTime: 1705700000000,
+                    lastUpdatedTime: 1705800000000,
+                },
+                {
+                    conversationId: '19:xyz@thread.v2',
+                    createdTime: 1705600000000,
+                    lastUpdatedTime: 1705750000000,
+                },
+            ],
+        },
+    ],
+};