msteams-mcp 0.23.0 → 0.25.0

package/README.md

@@ -76,8 +76,9 @@ The server uses your system's Chrome (macOS/Linux) or Edge (Windows) for authent
 |------|-------------|
 | `teams_search` | Search Teams messages with operators (`from:`, `sent:`, `in:`, `hasattachment:`, etc.) |
 | `teams_search_email` | Search emails in your mailbox (same auth as Teams — no extra login) |
-| `teams_get_message` | Get a single message by ID with full content (any age) |
-| `teams_get_thread` | Get messages from a conversation/thread |
+| `teams_list_chats` | List recent conversations (1:1, group, meeting, channel) with a last-message preview |
+| `teams_get_message` | Get a single message by ID with full content (any age); includes reactions |
+| `teams_get_thread` | Get messages from a conversation/thread; includes reactions; `threadRootId` scopes to one channel thread; `fromUrl` accepts a Teams message deep link |
 | `teams_find_channel` | Find channels by name (your teams + org-wide discovery) |
 | `teams_get_activity` | Get activity feed (mentions, reactions, replies, notifications) |
 
@@ -85,8 +86,9 @@ The server uses your system's Chrome (macOS/Linux) or Edge (Windows) for authent
 
 | 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_send_message` | Send a message (default: self-chat/notes). `replyToMessageId` for thread replies, `subject` for a new channel thread, `scheduleAt` to schedule, `contentType` (`auto`/`text`/`html`/`markdown`) to control formatting |
+| `teams_wait_for_reply` | Block until a new message arrives (server-side poll, capped ~110s); idempotent `after`/`nextAfter` cursor — pair with `teams_send_message` |
+| `teams_edit_message` | Edit one of your own messages (`contentType` supported) |
 | `teams_delete_message` | Delete one of your own messages (soft delete) |
 
 ### People & Contacts
@@ -96,6 +98,7 @@ The server uses your system's Chrome (macOS/Linux) or Edge (Windows) for authent
 | `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_person` | Resolve one or more MRIs to full profiles (name, email, job title, department) |
 | `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) |
 
@@ -257,7 +260,6 @@ Development commands:
 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
 ```

package/dist/api/chatsvc-api.d.ts

@@ -10,6 +10,7 @@
  * - chatsvc-reactions: add/remove emoji reactions
  * - chatsvc-virtual: saved messages, followed threads, save/unsave
  * - chatsvc-readstatus: consumption horizons, mark as read, unread counts
+ * - chatsvc-conversations: recent conversation list (chats, groups, channels)
  * - chatsvc-common: shared utilities (date formatting)
  */
 export * from './chatsvc-messaging.js';
@@ -17,4 +18,5 @@ export * from './chatsvc-activity.js';
 export * from './chatsvc-reactions.js';
 export * from './chatsvc-virtual.js';
 export * from './chatsvc-readstatus.js';
+export * from './chatsvc-conversations.js';
 export * from './chatsvc-common.js';

package/dist/api/chatsvc-api.js

@@ -10,6 +10,7 @@
  * - chatsvc-reactions: add/remove emoji reactions
  * - chatsvc-virtual: saved messages, followed threads, save/unsave
  * - chatsvc-readstatus: consumption horizons, mark as read, unread counts
+ * - chatsvc-conversations: recent conversation list (chats, groups, channels)
  * - chatsvc-common: shared utilities (date formatting)
  */
 // Re-export everything from sub-modules to maintain backward compatibility
@@ -18,4 +19,5 @@ export * from './chatsvc-activity.js';
 export * from './chatsvc-reactions.js';
 export * from './chatsvc-virtual.js';
 export * from './chatsvc-readstatus.js';
+export * from './chatsvc-conversations.js';
 export * from './chatsvc-common.js';

package/dist/api/chatsvc-conversations.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Chat Service API - Conversation list.
+ *
+ * Lists the user's recent conversations (1:1 chats, group chats, meetings and
+ * channels) with a last-message preview, via the chatsvc conversations endpoint.
+ */
+import { type Result } from '../types/result.js';
+/** A summarised conversation as returned by the chat list. */
+export interface ChatSummary {
+    conversationId: string;
+    /** Channel/group topic, or empty for 1:1 chats. */
+    topic: string;
+    chatType: 'channel' | 'meeting' | 'group' | 'oneOnOne' | 'chat';
+    /** ISO timestamp of the last message, or empty if unknown. */
+    lastMessageTime: string;
+    /** Display name of the last message's sender. */
+    lastMessageFrom: string;
+    /** Plain-text preview of the last message, truncated. */
+    lastMessagePreview: string;
+}
+/** Result of listing conversations. */
+export interface GetConversationsResult {
+    conversations: ChatSummary[];
+}
+/**
+ * Parses a raw chatsvc conversation into a {@link ChatSummary}, or null if it
+ * has no usable ID. Pure — no IO — so the field mapping and truncation are
+ * unit-testable against fixture JSON.
+ */
+export declare function parseConversation(raw: Record<string, unknown>): ChatSummary | null;
+/**
+ * Lists the user's recent conversations (chats, group chats, meetings and
+ * channels), newest activity first, capped at `limit`.
+ */
+export declare function getConversations(options?: {
+    limit?: number;
+}): Promise<Result<GetConversationsResult>>;

package/dist/api/chatsvc-conversations.js

@@ -0,0 +1,85 @@
+/**
+ * Chat Service API - Conversation list.
+ *
+ * Lists the user's recent conversations (1:1 chats, group chats, meetings and
+ * channels) with a last-message preview, via the chatsvc conversations endpoint.
+ */
+import { httpRequest } from '../utils/http.js';
+import { CHATSVC_API, getSkypeAuthHeaders } from '../utils/api-config.js';
+import { ok } from '../types/result.js';
+import { requireMessageAuthWithConfig } from '../utils/auth-guards.js';
+import { stripHtml } from '../utils/parsers.js';
+import { DEFAULT_THREAD_LIMIT } from '../constants.js';
+/** Maximum length of a last-message preview before truncation. */
+const PREVIEW_MAX_LENGTH = 120;
+/** Classifies a conversation type from its ID. */
+function classifyChatType(id) {
+    if (id.includes('meeting_'))
+        return 'meeting';
+    if (id.includes('@thread.tacv2'))
+        return 'channel';
+    if (id.includes('@unq.gbl.spaces'))
+        return 'oneOnOne';
+    if (id.includes('@thread.v2'))
+        return 'group';
+    return 'chat';
+}
+/** Truncates a preview to {@link PREVIEW_MAX_LENGTH} characters, adding an ellipsis. */
+function truncatePreview(text) {
+    if (text.length <= PREVIEW_MAX_LENGTH)
+        return text;
+    return `${text.slice(0, PREVIEW_MAX_LENGTH)}…`;
+}
+/**
+ * Parses a raw chatsvc conversation into a {@link ChatSummary}, or null if it
+ * has no usable ID. Pure — no IO — so the field mapping and truncation are
+ * unit-testable against fixture JSON.
+ */
+export function parseConversation(raw) {
+    const id = typeof raw.id === 'string' ? raw.id : '';
+    if (!id)
+        return null;
+    const threadProperties = (raw.threadProperties ?? {});
+    const topic = typeof threadProperties.topic === 'string' ? threadProperties.topic : '';
+    const lastMessage = (raw.lastMessage ?? {});
+    const lastMessageTime = (typeof lastMessage.originalarrivaltime === 'string' && lastMessage.originalarrivaltime) ||
+        (typeof lastMessage.composetime === 'string' && lastMessage.composetime) ||
+        '';
+    const lastMessageFrom = typeof lastMessage.imdisplayname === 'string' ? lastMessage.imdisplayname : '';
+    const rawContent = typeof lastMessage.content === 'string' ? lastMessage.content : '';
+    return {
+        conversationId: id,
+        topic,
+        chatType: classifyChatType(id),
+        lastMessageTime,
+        lastMessageFrom,
+        lastMessagePreview: truncatePreview(stripHtml(rawContent)),
+    };
+}
+/**
+ * Lists the user's recent conversations (chats, group chats, meetings and
+ * channels), newest activity first, capped at `limit`.
+ */
+export async function getConversations(options = {}) {
+    const authResult = requireMessageAuthWithConfig();
+    if (!authResult.ok) {
+        return authResult;
+    }
+    const { auth, region, baseUrl } = authResult.value;
+    const limit = options.limit ?? DEFAULT_THREAD_LIMIT;
+    const response = await httpRequest(CHATSVC_API.conversations(region, baseUrl), {
+        method: 'GET',
+        headers: getSkypeAuthHeaders(auth.skypeToken, auth.authToken, baseUrl),
+    });
+    if (!response.ok) {
+        return response;
+    }
+    const raw = Array.isArray(response.value.data.conversations)
+        ? response.value.data.conversations
+        : [];
+    const conversations = raw
+        .map(c => parseConversation(c))
+        .filter((c) => c !== null)
+        .slice(0, limit);
+    return ok({ conversations });
+}

package/dist/api/chatsvc-conversations.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Unit tests for conversation-list parsing.
+ */
+export {};

package/dist/api/chatsvc-conversations.test.js

@@ -0,0 +1,51 @@
+/**
+ * Unit tests for conversation-list parsing.
+ */
+import { describe, it, expect } from 'vitest';
+import { parseConversation } from './chatsvc-conversations.js';
+describe('parseConversation', () => {
+    it('parses a 1:1 chat with a last-message preview', () => {
+        const result = parseConversation({
+            id: '19:aaa_bbb@unq.gbl.spaces',
+            lastMessage: {
+                imdisplayname: 'Bob',
+                content: '<p>Hi there</p>',
+                originalarrivaltime: '2026-06-30T10:00:00Z',
+            },
+        });
+        expect(result).toEqual({
+            conversationId: '19:aaa_bbb@unq.gbl.spaces',
+            topic: '',
+            chatType: 'oneOnOne',
+            lastMessageTime: '2026-06-30T10:00:00Z',
+            lastMessageFrom: 'Bob',
+            lastMessagePreview: 'Hi there',
+        });
+    });
+    it('classifies channel, group and meeting conversation IDs', () => {
+        expect(parseConversation({ id: '19:x@thread.tacv2', threadProperties: { topic: 'General' } })?.chatType).toBe('channel');
+        expect(parseConversation({ id: '19:x@thread.v2' })?.chatType).toBe('group');
+        expect(parseConversation({ id: '19:meeting_x@thread.v2' })?.chatType).toBe('meeting');
+    });
+    it('uses the channel/group topic when present', () => {
+        const result = parseConversation({ id: '19:x@thread.tacv2', threadProperties: { topic: 'General' } });
+        expect(result?.topic).toBe('General');
+    });
+    it('truncates a long preview to 120 characters with an ellipsis', () => {
+        const long = 'a'.repeat(200);
+        const result = parseConversation({ id: '19:x@thread.v2', lastMessage: { content: long } });
+        expect(result?.lastMessagePreview.length).toBe(121); // 120 chars + ellipsis
+        expect(result?.lastMessagePreview.endsWith('…')).toBe(true);
+    });
+    it('returns null when the conversation has no id', () => {
+        expect(parseConversation({})).toBeNull();
+        expect(parseConversation({ id: '' })).toBeNull();
+    });
+    it('falls back to composetime when originalarrivaltime is absent', () => {
+        const result = parseConversation({
+            id: '19:x@thread.v2',
+            lastMessage: { composetime: '2026-06-30T09:00:00Z', content: 'hey' },
+        });
+        expect(result?.lastMessageTime).toBe('2026-06-30T09:00:00Z');
+    });
+});

package/dist/api/chatsvc-messaging.d.ts

@@ -5,11 +5,13 @@
  * Conversation properties and participant extraction.
  */
 import { type Result } from '../types/result.js';
-import { type ExtractedLink } from '../utils/parsers.js';
+import { type ExtractedLink, type Reaction, type ReactionSummary } from '../utils/parsers.js';
 /** Result of sending a message. */
 export interface SendMessageResult {
     messageId: string;
     timestamp?: number;
+    /** For scheduled messages: the ISO 8601 UTC time the message will be sent. */
+    scheduledFor?: string;
 }
 /** A message from a thread/conversation. */
 export interface ThreadMessage {
@@ -32,6 +34,10 @@ export interface ThreadMessage {
     threadRootId?: string;
     /** True if this message is a reply within a channel thread (not a top-level post) */
     isThreadReply?: boolean;
+    /** Emoji reactions on this message, with reactor identity (names resolved where possible). */
+    reactions?: Reaction[];
+    /** Reaction counts keyed by emoji (e.g. { like: 3, heart: 1 }). */
+    reactionSummary?: ReactionSummary;
 }
 /** Result of getting thread messages. */
 export interface GetThreadResult {
@@ -68,6 +74,24 @@ export interface SendMessageOptions {
      * are part of the same flat conversation.
      */
     replyToMessageId?: string;
+    /**
+     * How to interpret the content. Defaults to `markdown` (convert markdown +
+     * @mentions + links to Teams HTML — the historical behaviour). Use `text` to
+     * send verbatim with no reinterpretation, `html` for caller-supplied Teams
+     * HTML, or `auto` to convert only when markdown/mention syntax is present.
+     */
+    contentType?: ContentType;
+    /**
+     * For channel posts: a thread subject/title. Starts a new titled thread.
+     * Ignored for 1:1/group chats (they have no per-message subject).
+     */
+    subject?: string;
+    /**
+     * Schedule the message for future delivery. ISO 8601 (e.g.
+     * "2026-04-11T09:00:00Z"); a timezone-less value is treated as UTC. Cannot be
+     * combined with mentions or a thread reply.
+     */
+    scheduleAt?: string;
 }
 /** Result of getting a 1:1 conversation. */
 export interface GetOneOnOneChatResult {
@@ -116,11 +140,13 @@ export declare function getMessage(conversationId: string, messageId: string): P
  * @param options.limit - Maximum messages to return (default 50)
  * @param options.startTime - Fetch messages from this timestamp onwards
  * @param options.order - Sort order: 'desc' (newest-first, default) or 'asc' (oldest-first)
+ * @param options.replyToMessageId - For channels: scope to replies of a specific top-level post
  */
 export declare function getThreadMessages(conversationId: string, options?: {
     limit?: number;
     startTime?: number;
     order?: 'asc' | 'desc';
+    replyToMessageId?: string;
 }): Promise<Result<GetThreadResult>>;
 /**
  * Edits an existing message.
@@ -132,9 +158,10 @@ export declare function getThreadMessages(conversationId: string, options?: {
  *
  * @param conversationId - The conversation containing the message
  * @param messageId - The ID of the message to edit
- * @param newContent - New content (markdown; supports mentions like sendMessage)
+ * @param newContent - New content (markdown by default; supports mentions like sendMessage)
+ * @param contentType - How to interpret the content (default `markdown`)
  */
-export declare function editMessage(conversationId: string, messageId: string, newContent: string): Promise<Result<EditMessageResult>>;
+export declare function editMessage(conversationId: string, messageId: string, newContent: string, contentType?: ContentType): Promise<Result<EditMessageResult>>;
 /**
  * Deletes a message (soft delete).
  *
@@ -206,3 +233,128 @@ export declare function parseContentWithMentionsAndLinks(content: string): {
     html: string;
     mentions: Mention[];
 };
+/** How message content should be interpreted before sending. */
+export type ContentType = 'auto' | 'text' | 'html' | 'markdown';
+/** Content resolved into the shape the chatsvc/Graph message body expects. */
+export interface ResolvedContent {
+    /** The body content to send. */
+    content: string;
+    /** The wire message type: plain `Text` or `RichText/Html`. */
+    messagetype: 'Text' | 'RichText/Html';
+    /** Any @mentions extracted from the content (empty for text/html modes). */
+    mentions: Mention[];
+}
+/**
+ * Resolves outbound message content according to the requested content type.
+ *
+ * - `markdown` (default): convert markdown + @mentions + links to Teams HTML.
+ *   This preserves the historical behaviour where all content was converted.
+ * - `text`: send verbatim as plain text — no markdown, mention or link
+ *   processing. The escape hatch for content that should not be reinterpreted
+ *   (e.g. `5*3*2`, `a_b_c`).
+ * - `html`: caller-supplied Teams HTML, sent as `RichText/Html` unchanged.
+ * - `auto`: convert only when the content actually contains markdown formatting
+ *   or mention/link syntax; otherwise send plain text.
+ */
+export declare function resolveMessageContent(content: string, contentType?: ContentType): ResolvedContent;
+/**
+ * Parses and validates a schedule datetime for a scheduled message.
+ *
+ * Accepts ISO 8601 (with or without a timezone) and a space-separated
+ * `YYYY-MM-DD HH:mm[:ss]` form. A timezone-less value is treated as UTC (so
+ * results are deterministic regardless of the host clock). Rejects unparseable
+ * or past times. `now` is injectable for testing.
+ */
+export declare function parseScheduleTime(input: string, now?: number): Result<{
+    iso: string;
+    epochMs: number;
+}>;
+/**
+ * Builds the chatsvc `/drafts` request body for a scheduled message — the same
+ * mechanism the Teams web client uses. `sendAt` must be epoch milliseconds.
+ */
+export declare function buildScheduledDraftBody(opts: {
+    conversationId: string;
+    content: string;
+    messagetype: 'Text' | 'RichText/Html';
+    epochMs: number;
+    userMri: string;
+    isoNow: string;
+    conversationLink: string;
+    clientMessageId: string;
+}): Record<string, unknown>;
+/**
+ * Extracts the two member object IDs from a 1:1 conversation ID of the form
+ * `19:<a>_<b>@unq.gbl.spaces`. Returns null for any other conversation type or
+ * a malformed ID (so the caller only attempts thread creation for real 1:1s).
+ */
+export declare function extractOneOnOneMemberIds(conversationId: string): string[] | null;
+/**
+ * Builds the `/v1/threads` body that creates the unique-roster 1:1 thread — what
+ * the Teams client does the first time you message someone. Both members are
+ * added as Admins with the fixed unique-roster properties.
+ */
+export declare function buildOneOnOneThreadBody(memberIds: string[]): Record<string, unknown>;
+/** Result of waiting for a new message in a conversation. */
+export interface WaitForReplyResult {
+    /** True if the wait timed out before any new message arrived. */
+    timedOut: boolean;
+    /** The baseline message ID the wait started from. */
+    after: string;
+    /** Resume cursor: pass as `after` to a follow-up wait to continue from here. */
+    nextAfter: string;
+    /** The new messages that arrived (oldest first), or empty on timeout. */
+    newMessages: ThreadMessage[];
+    /** How many poll iterations ran. */
+    polls: number;
+    /** How many seconds the wait blocked for. */
+    waitedSeconds: number;
+}
+/** Options for {@link waitForReply}. */
+export interface WaitForReplyOptions {
+    /** Only return messages newer than this message ID. Defaults to the caller's most recent message. */
+    after?: string;
+    /** Maximum seconds to block (clamped to MAX_WAIT_SECONDS). */
+    maxWaitSeconds?: number;
+    /** Seconds between polls. */
+    intervalSeconds?: number;
+    /** Include the caller's own messages in the result (default false). */
+    includeSelf?: boolean;
+    /** Messages fetched per poll (default 50). */
+    limit?: number;
+}
+/** Clamps the wait timing knobs into their sane range (pure, for testability). */
+export declare function clampWaitParams(maxWaitSeconds: number, intervalSeconds: number): {
+    maxWait: number;
+    interval: number;
+};
+/**
+ * Selects the messages strictly newer than `afterId`, oldest first. Excludes the
+ * caller's own messages unless `includeSelf` is set; ignores non-numeric IDs.
+ * Pure so the filter/sort semantics are unit-testable.
+ */
+export declare function selectNewMessages<T extends {
+    id: string;
+    isFromMe?: boolean;
+}>(messages: readonly T[], afterId: number, includeSelf: boolean): T[];
+/**
+ * Resolves the baseline message ID for a wait with no explicit `after`: the
+ * caller's own most recent message, else the most recent message overall, else
+ * 0 for an empty thread. Anchoring to the caller's own last message makes a wait
+ * restarted after a send idempotent without remembering the sent ID. Pure.
+ */
+export declare function resolveWaitBaseline(messages: readonly {
+    id: string;
+    isFromMe?: boolean;
+}[]): number;
+/**
+ * Blocks until a new message appears in a conversation, then returns only the
+ * new messages. Polls inside the call so a waiting agent makes a single tool
+ * call instead of a poll loop. Read-only and idempotent: it never posts, and the
+ * `after` baseline makes a restart resume from the same point without replaying.
+ *
+ * The block is capped at MAX_WAIT_SECONDS so an MCP client timeout never kills
+ * the call; on timeout it returns `timedOut: true` with `nextAfter` so the
+ * caller can simply call again to keep waiting.
+ */
+export declare function waitForReply(conversationId: string, options?: WaitForReplyOptions): Promise<Result<WaitForReplyResult>>;