msteams-mcp 0.2.1

package/dist/tools/people-tools.d.ts

@@ -0,0 +1,46 @@
+/**
+ * People-related tool handlers.
+ */
+import { z } from 'zod';
+import type { RegisteredTool } from './index.js';
+export declare const SearchPeopleInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    query: string;
+}, {
+    query: string;
+    limit?: number | undefined;
+}>;
+export declare const FrequentContactsInputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+}, {
+    limit?: number | undefined;
+}>;
+export declare const getMeTool: RegisteredTool<z.ZodObject<Record<string, never>>>;
+export declare const searchPeopleTool: RegisteredTool<typeof SearchPeopleInputSchema>;
+export declare const frequentContactsTool: RegisteredTool<typeof FrequentContactsInputSchema>;
+/** All people-related tools. */
+export declare const peopleTools: (RegisteredTool<z.ZodObject<Record<string, never>, z.UnknownKeysParam, z.ZodTypeAny, {
+    [x: string]: never;
+}, {
+    [x: string]: never;
+}>> | RegisteredTool<z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    query: string;
+}, {
+    query: string;
+    limit?: number | undefined;
+}>> | RegisteredTool<z.ZodObject<{
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+}, {
+    limit?: number | undefined;
+}>>)[];

package/dist/tools/people-tools.js

@@ -0,0 +1,112 @@
+/**
+ * People-related tool handlers.
+ */
+import { z } from 'zod';
+import { handleApiResult } from './index.js';
+import { searchPeople, getFrequentContacts } from '../api/substrate-api.js';
+import { getUserProfile } from '../auth/token-extractor.js';
+import { ErrorCode, createError } from '../types/errors.js';
+import { DEFAULT_PEOPLE_LIMIT, MAX_PEOPLE_LIMIT, DEFAULT_CONTACTS_LIMIT, MAX_CONTACTS_LIMIT, } from '../constants.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Schemas
+// ─────────────────────────────────────────────────────────────────────────────
+export const SearchPeopleInputSchema = z.object({
+    query: z.string().min(1, 'Query cannot be empty'),
+    limit: z.number().min(1).max(MAX_PEOPLE_LIMIT).optional().default(DEFAULT_PEOPLE_LIMIT),
+});
+export const FrequentContactsInputSchema = z.object({
+    limit: z.number().min(1).max(MAX_CONTACTS_LIMIT).optional().default(DEFAULT_CONTACTS_LIMIT),
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Definitions
+// ─────────────────────────────────────────────────────────────────────────────
+const getMeToolDefinition = {
+    name: 'teams_get_me',
+    description: 'Get the current user\'s profile information including email, display name, and Teams ID. Useful for finding @mentions or identifying the current user.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+};
+const searchPeopleToolDefinition = {
+    name: 'teams_search_people',
+    description: 'Search for people in Microsoft Teams by name or email. Returns matching users with display name, email, job title, and department. Useful for finding someone to message.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Search term - can be a name, email address, or partial match',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum number of results to return (default: 10)',
+            },
+        },
+        required: ['query'],
+    },
+};
+const frequentContactsToolDefinition = {
+    name: 'teams_get_frequent_contacts',
+    description: 'Get the user\'s frequently contacted people, ranked by interaction frequency. Useful for resolving ambiguous names (e.g., "Rob" → which Rob?) by checking who the user commonly works with. Returns display name, email, job title, and department.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: {
+                type: 'number',
+                description: 'Maximum number of contacts to return (default: 50)',
+            },
+        },
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Handlers
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleGetMe(_input, _ctx) {
+    const profile = getUserProfile();
+    if (!profile) {
+        return {
+            success: false,
+            error: createError(ErrorCode.AUTH_REQUIRED, 'No valid session. Please use teams_login first.'),
+        };
+    }
+    return {
+        success: true,
+        data: { profile },
+    };
+}
+async function handleSearchPeople(input, _ctx) {
+    const result = await searchPeople(input.query, input.limit);
+    return handleApiResult(result, (value) => ({
+        query: input.query,
+        returned: value.returned,
+        results: value.results,
+    }));
+}
+async function handleGetFrequentContacts(input, _ctx) {
+    const result = await getFrequentContacts(input.limit);
+    return handleApiResult(result, (value) => ({
+        returned: value.returned,
+        contacts: value.results,
+    }));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────────────────────
+export const getMeTool = {
+    definition: getMeToolDefinition,
+    schema: z.object({}),
+    handler: handleGetMe,
+};
+export const searchPeopleTool = {
+    definition: searchPeopleToolDefinition,
+    schema: SearchPeopleInputSchema,
+    handler: handleSearchPeople,
+};
+export const frequentContactsTool = {
+    definition: frequentContactsToolDefinition,
+    schema: FrequentContactsInputSchema,
+    handler: handleGetFrequentContacts,
+};
+/** All people-related tools. */
+export const peopleTools = [getMeTool, searchPeopleTool, frequentContactsTool];

package/dist/tools/registry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool registry - centralised tool management.
+ *
+ * All tools are registered here and can be looked up by name.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RegisteredTool, ToolContext, ToolResult } from './index.js';
+/**
+ * Gets all tool definitions for MCP ListTools.
+ */
+export declare function getToolDefinitions(): Tool[];
+/**
+ * Gets a tool by name.
+ */
+export declare function getTool(name: string): RegisteredTool<any> | undefined;
+/**
+ * Invokes a tool by name with the given arguments and context.
+ */
+export declare function invokeTool(name: string, args: unknown, ctx: ToolContext): Promise<ToolResult>;
+/**
+ * Checks if a tool exists.
+ */
+export declare function hasTool(name: string): boolean;

package/dist/tools/registry.js

@@ -0,0 +1,63 @@
+/**
+ * Tool registry - centralised tool management.
+ *
+ * All tools are registered here and can be looked up by name.
+ */
+import { searchTools } from './search-tools.js';
+import { messageTools } from './message-tools.js';
+import { peopleTools } from './people-tools.js';
+import { authTools } from './auth-tools.js';
+import { meetingTools } from './meeting-tools.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry
+// ─────────────────────────────────────────────────────────────────────────────
+/** All registered tools (cast to base type for registry). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const allTools = [
+    ...searchTools,
+    ...messageTools,
+    ...peopleTools,
+    ...authTools,
+    ...meetingTools,
+];
+/** Lookup map for tools by name. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const toolsByName = new Map(allTools.map(tool => [tool.definition.name, tool]));
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Gets all tool definitions for MCP ListTools.
+ */
+export function getToolDefinitions() {
+    return allTools.map(tool => tool.definition);
+}
+/**
+ * Gets a tool by name.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getTool(name) {
+    return toolsByName.get(name);
+}
+/**
+ * Invokes a tool by name with the given arguments and context.
+ */
+export async function invokeTool(name, args, ctx) {
+    const tool = toolsByName.get(name);
+    if (!tool) {
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    // Validate input
+    const parseResult = tool.schema.safeParse(args);
+    if (!parseResult.success) {
+        throw new Error(`Invalid input: ${parseResult.error.message}`);
+    }
+    // Invoke handler
+    return tool.handler(parseResult.data, ctx);
+}
+/**
+ * Checks if a tool exists.
+ */
+export function hasTool(name) {
+    return toolsByName.has(name);
+}

package/dist/tools/search-tools.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Search-related tool handlers.
+ */
+import { z } from 'zod';
+import type { RegisteredTool } from './index.js';
+export declare const SearchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    from: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    query: string;
+    maxResults: number;
+    size: number;
+}, {
+    query: string;
+    from?: number | undefined;
+    maxResults?: number | undefined;
+    size?: number | undefined;
+}>;
+export declare const GetThreadInputSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    markRead: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    order: z.ZodDefault<z.ZodOptional<z.ZodEnum<["asc", "desc"]>>>;
+}, "strip", z.ZodTypeAny, {
+    conversationId: string;
+    limit: number;
+    markRead: boolean;
+    order: "desc" | "asc";
+}, {
+    conversationId: string;
+    limit?: number | undefined;
+    markRead?: boolean | undefined;
+    order?: "desc" | "asc" | undefined;
+}>;
+export declare const FindChannelInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    query: string;
+}, {
+    query: string;
+    limit?: number | undefined;
+}>;
+export declare const searchTool: RegisteredTool<typeof SearchInputSchema>;
+export declare const getThreadTool: RegisteredTool<typeof GetThreadInputSchema>;
+export declare const findChannelTool: RegisteredTool<typeof FindChannelInputSchema>;
+/** All search-related tools. */
+export declare const searchTools: (RegisteredTool<z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    from: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    query: string;
+    maxResults: number;
+    size: number;
+}, {
+    query: string;
+    from?: number | undefined;
+    maxResults?: number | undefined;
+    size?: number | undefined;
+}>> | RegisteredTool<z.ZodObject<{
+    conversationId: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    markRead: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    order: z.ZodDefault<z.ZodOptional<z.ZodEnum<["asc", "desc"]>>>;
+}, "strip", z.ZodTypeAny, {
+    conversationId: string;
+    limit: number;
+    markRead: boolean;
+    order: "desc" | "asc";
+}, {
+    conversationId: string;
+    limit?: number | undefined;
+    markRead?: boolean | undefined;
+    order?: "desc" | "asc" | undefined;
+}>> | RegisteredTool<z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    query: string;
+}, {
+    query: string;
+    limit?: number | undefined;
+}>>)[];

package/dist/tools/search-tools.js

@@ -0,0 +1,222 @@
+/**
+ * Search-related tool handlers.
+ */
+import { z } from 'zod';
+import { handleApiResult } from './index.js';
+import { searchMessages, searchChannels } from '../api/substrate-api.js';
+import { getThreadMessages, getConsumptionHorizon, markAsRead } from '../api/chatsvc-api.js';
+import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, DEFAULT_THREAD_LIMIT, MAX_THREAD_LIMIT, DEFAULT_CHANNEL_LIMIT, MAX_CHANNEL_LIMIT, } from '../constants.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Schemas
+// ─────────────────────────────────────────────────────────────────────────────
+export const SearchInputSchema = z.object({
+    query: z.string().min(1, 'Query cannot be empty'),
+    maxResults: z.number().optional().default(DEFAULT_PAGE_SIZE),
+    from: z.number().min(0).optional().default(0),
+    size: z.number().min(1).max(MAX_PAGE_SIZE).optional().default(DEFAULT_PAGE_SIZE),
+});
+export const GetThreadInputSchema = z.object({
+    conversationId: z.string().min(1, 'Conversation ID cannot be empty'),
+    limit: z.number().min(1).max(MAX_THREAD_LIMIT).optional().default(DEFAULT_THREAD_LIMIT),
+    markRead: z.boolean().optional().default(false),
+    order: z.enum(['asc', 'desc']).optional().default('desc'),
+});
+export const FindChannelInputSchema = z.object({
+    query: z.string().min(1, 'Query cannot be empty'),
+    limit: z.number().min(1).max(MAX_CHANNEL_LIMIT).optional().default(DEFAULT_CHANNEL_LIMIT),
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Definitions
+// ─────────────────────────────────────────────────────────────────────────────
+const searchToolDefinition = {
+    name: 'teams_search',
+    description: 'Search for messages in Microsoft Teams. Returns matching messages with sender, timestamp, content, conversationId (for replies), and pagination info. Supports operators: from:email, to:name, sent:YYYY-MM-DD, sent:today, is:Messages, is:Meetings, is:Channels, is:Chats, hasattachment:true, "Name" for @mentions. The in:channel operator only works reliably when combined with content (e.g., "meeting in:IT Support"). Combine with NOT to exclude. Results sorted by recency.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Search query with optional operators. WORKING: from:email (or name), to:name (spaces not dots - "to:rob macdonald"), sent:YYYY-MM-DD, sent:>=YYYY-MM-DD, sent:today, is:Messages, is:Meetings, is:Channels, is:Chats (case-sensitive, plural required), hasattachment:true, "Display Name" for @mentions. CHANNEL FILTER: in:channel only works reliably WITH content terms (e.g., "budget in:IT Support"). NEVER quote channel names. NOT WORKING: mentions:, sent:lastweek, @me, from:me, is:meeting (must be is:Meetings). Use teams_get_me first to get email/displayName.',
+            },
+            maxResults: {
+                type: 'number',
+                description: 'Maximum number of results to return (default: 25)',
+            },
+            from: {
+                type: 'number',
+                description: 'Starting offset for pagination (0-based, default: 0). Use this to get subsequent pages of results.',
+            },
+            size: {
+                type: 'number',
+                description: 'Page size (default: 25). Number of results per page.',
+            },
+        },
+        required: ['query'],
+    },
+};
+const getThreadToolDefinition = {
+    name: 'teams_get_thread',
+    description: 'Get messages from a Teams conversation/thread. Default: newest-first (latest messages at top). For channels: messages include isThreadReply (true for replies) and threadRootId (ID of the post being replied to). Messages without threadRootId are top-level posts. Use threadRootId to group related messages. Each message includes a "when" field with the day of week (e.g., "Friday, January 30, 2026, 10:45 AM UTC"). Returns unread count and can optionally mark as read.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            conversationId: {
+                type: 'string',
+                description: 'The conversation ID to get messages from (e.g., "19:abc@thread.tacv2" from search results)',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum number of messages to return (default: 50, max: 200)',
+            },
+            markRead: {
+                type: 'boolean',
+                description: 'If true, marks the conversation as read up to the latest message after fetching (default: false)',
+            },
+            order: {
+                type: 'string',
+                enum: ['asc', 'desc'],
+                description: 'Sort order: "desc" (newest-first, default) or "asc" (oldest-first for chronological reading)',
+            },
+        },
+        required: ['conversationId'],
+    },
+};
+const findChannelToolDefinition = {
+    name: 'teams_find_channel',
+    description: 'Find Teams channels by name. Searches both (1) channels in teams you\'re a member of (reliable) and (2) channels across the organisation (discovery). Results indicate whether you\'re already a member via the isMember field. Channel IDs can be used with teams_get_thread to read messages.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Channel name to search for (partial match)',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum number of results (default: 10, max: 50)',
+            },
+        },
+        required: ['query'],
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Handlers
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleSearch(input, _ctx) {
+    const result = await searchMessages(input.query, {
+        maxResults: input.maxResults,
+        from: input.from,
+        size: input.size,
+    });
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    return {
+        success: true,
+        data: {
+            query: input.query,
+            resultCount: result.value.results.length,
+            pagination: {
+                from: result.value.pagination.from,
+                size: result.value.pagination.size,
+                returned: result.value.pagination.returned,
+                total: result.value.pagination.total,
+                hasMore: result.value.pagination.hasMore,
+                nextFrom: result.value.pagination.hasMore
+                    ? result.value.pagination.from + result.value.pagination.returned
+                    : undefined,
+            },
+            results: result.value.results,
+        },
+    };
+}
+async function handleGetThread(input, _ctx) {
+    const result = await getThreadMessages(input.conversationId, {
+        limit: input.limit,
+        order: input.order,
+    });
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    // Get unread status
+    let unreadCount;
+    let lastReadMessageId;
+    const horizonResult = await getConsumptionHorizon(input.conversationId);
+    if (horizonResult.ok) {
+        lastReadMessageId = horizonResult.value.lastReadMessageId;
+        // Count messages after last read
+        if (lastReadMessageId) {
+            let foundLastRead = false;
+            unreadCount = 0;
+            for (const msg of result.value.messages) {
+                if (msg.id === lastReadMessageId) {
+                    foundLastRead = true;
+                    continue;
+                }
+                if (foundLastRead && !msg.isFromMe) {
+                    unreadCount++;
+                }
+            }
+            // If last read message wasn't found, it's older than our window - all messages are unread
+            if (!foundLastRead) {
+                unreadCount = result.value.messages.filter(m => !m.isFromMe).length;
+            }
+        }
+        else {
+            // No consumption horizon means all messages are unread (new conversation)
+            unreadCount = result.value.messages.filter(m => !m.isFromMe).length;
+        }
+    }
+    // Mark as read if requested
+    let markedAsRead = false;
+    if (input.markRead && result.value.messages.length > 0) {
+        // Find the latest message - depends on sort order
+        // desc (default): newest is first [0], asc: newest is last [-1]
+        const latestMessage = input.order === 'asc'
+            ? result.value.messages[result.value.messages.length - 1]
+            : result.value.messages[0];
+        if (latestMessage) {
+            const markResult = await markAsRead(input.conversationId, latestMessage.id);
+            markedAsRead = markResult.ok;
+        }
+    }
+    return {
+        success: true,
+        data: {
+            conversationId: result.value.conversationId,
+            messageCount: result.value.messages.length,
+            unreadCount,
+            lastReadMessageId,
+            markedAsRead: input.markRead ? markedAsRead : undefined,
+            messages: result.value.messages,
+        },
+    };
+}
+async function handleFindChannel(input, _ctx) {
+    const result = await searchChannels(input.query, input.limit);
+    return handleApiResult(result, (value) => ({
+        query: input.query,
+        count: value.returned,
+        channels: value.results,
+    }));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────────────────────
+export const searchTool = {
+    definition: searchToolDefinition,
+    schema: SearchInputSchema,
+    handler: handleSearch,
+};
+export const getThreadTool = {
+    definition: getThreadToolDefinition,
+    schema: GetThreadInputSchema,
+    handler: handleGetThread,
+};
+export const findChannelTool = {
+    definition: findChannelToolDefinition,
+    schema: FindChannelInputSchema,
+    handler: handleFindChannel,
+};
+/** All search-related tools. */
+export const searchTools = [searchTool, getThreadTool, findChannelTool];

package/dist/types/errors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Error taxonomy for MCP operations.
+ *
+ * Provides machine-readable error codes that help LLMs
+ * understand failures and take appropriate action.
+ */
+/** Enumeration of all error types in the system. */
+export declare enum ErrorCode {
+    /** No valid authentication token or session. */
+    AUTH_REQUIRED = "AUTH_REQUIRED",
+    /** Token has expired and needs refresh. */
+    AUTH_EXPIRED = "AUTH_EXPIRED",
+    /** Rate limited by the API. */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** Requested resource was not found. */
+    NOT_FOUND = "NOT_FOUND",
+    /** Invalid input parameters. */
+    INVALID_INPUT = "INVALID_INPUT",
+    /** API returned an error response. */
+    API_ERROR = "API_ERROR",
+    /** Browser automation failed. */
+    BROWSER_ERROR = "BROWSER_ERROR",
+    /** Network or connection error. */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** Operation timed out. */
+    TIMEOUT = "TIMEOUT",
+    /** Unknown or unexpected error. */
+    UNKNOWN = "UNKNOWN"
+}
+/** Structured error with machine-readable information. */
+export interface McpError {
+    /** Machine-readable error code. */
+    code: ErrorCode;
+    /** Human-readable error message. */
+    message: string;
+    /** Whether this error is potentially transient and retryable. */
+    retryable: boolean;
+    /** Suggested wait time before retry (milliseconds). */
+    retryAfterMs?: number;
+    /** Suggestions for resolving the error (for LLMs). */
+    suggestions: string[];
+}
+/**
+ * Creates a standardised MCP error.
+ */
+export declare function createError(code: ErrorCode, message: string, options?: {
+    retryable?: boolean;
+    retryAfterMs?: number;
+    suggestions?: string[];
+}): McpError;
+/**
+ * Classifies an HTTP status code into an error code.
+ */
+export declare function classifyHttpError(status: number, message?: string): ErrorCode;
+/**
+ * Extracts retry-after value from response headers.
+ */
+export declare function extractRetryAfter(headers: Headers): number | undefined;