msteams-mcp 0.2.0

package/dist/tools/people-tools.js

@@ -0,0 +1,123 @@
+/**
+ * People-related tool handlers.
+ */
+import { z } from 'zod';
+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);
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    return {
+        success: true,
+        data: {
+            query: input.query,
+            returned: result.value.returned,
+            results: result.value.results,
+        },
+    };
+}
+async function handleGetFrequentContacts(input, _ctx) {
+    const result = await getFrequentContacts(input.limit);
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    return {
+        success: true,
+        data: {
+            returned: result.value.returned,
+            contacts: result.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,61 @@
+/**
+ * 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';
+// ─────────────────────────────────────────────────────────────────────────────
+// 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,
+];
+/** 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,79 @@
+/**
+ * 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>>;
+}, "strip", z.ZodTypeAny, {
+    conversationId: string;
+    limit: number;
+}, {
+    conversationId: string;
+    limit?: number | undefined;
+}>;
+export declare const FindChannelInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    limit: number;
+}, {
+    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>>;
+}, "strip", z.ZodTypeAny, {
+    conversationId: string;
+    limit: number;
+}, {
+    conversationId: string;
+    limit?: number | undefined;
+}>> | RegisteredTool<z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    limit: number;
+}, {
+    query: string;
+    limit?: number | undefined;
+}>>)[];

package/dist/tools/search-tools.js

@@ -0,0 +1,168 @@
+/**
+ * Search-related tool handlers.
+ */
+import { z } from 'zod';
+import { searchMessages, searchChannels } from '../api/substrate-api.js';
+import { getThreadMessages } 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),
+});
+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 search operators: from:email, sent:today/lastweek, in:channel, hasattachment:true, "Name" for @mentions. Combine with NOT to exclude (e.g., NOT from:rob@co.com).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Search query with optional operators. Examples: "budget report", "from:sarah@co.com sent:lastweek", "\"Rob Smith\" NOT from:rob@co.com" (find @mentions of Rob). IMPORTANT: "@me", "from:me", "to:me" do NOT work - use teams_get_me first to get actual email/displayName, then use those values.',
+            },
+            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. Use this to see replies to a message, check thread context, or read recent messages in a chat. Requires a conversationId (available from search results).',
+    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)',
+            },
+        },
+        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 });
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    return {
+        success: true,
+        data: {
+            conversationId: result.value.conversationId,
+            messageCount: result.value.messages.length,
+            messages: result.value.messages,
+        },
+    };
+}
+async function handleFindChannel(input, _ctx) {
+    const result = await searchChannels(input.query, input.limit);
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    return {
+        success: true,
+        data: {
+            query: input.query,
+            count: result.value.returned,
+            channels: result.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;

package/dist/types/errors.js

@@ -0,0 +1,132 @@
+/**
+ * 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 var ErrorCode;
+(function (ErrorCode) {
+    /** No valid authentication token or session. */
+    ErrorCode["AUTH_REQUIRED"] = "AUTH_REQUIRED";
+    /** Token has expired and needs refresh. */
+    ErrorCode["AUTH_EXPIRED"] = "AUTH_EXPIRED";
+    /** Rate limited by the API. */
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    /** Requested resource was not found. */
+    ErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    /** Invalid input parameters. */
+    ErrorCode["INVALID_INPUT"] = "INVALID_INPUT";
+    /** API returned an error response. */
+    ErrorCode["API_ERROR"] = "API_ERROR";
+    /** Browser automation failed. */
+    ErrorCode["BROWSER_ERROR"] = "BROWSER_ERROR";
+    /** Network or connection error. */
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    /** Operation timed out. */
+    ErrorCode["TIMEOUT"] = "TIMEOUT";
+    /** Unknown or unexpected error. */
+    ErrorCode["UNKNOWN"] = "UNKNOWN";
+})(ErrorCode || (ErrorCode = {}));
+/**
+ * Creates a standardised MCP error.
+ */
+export function createError(code, message, options = {}) {
+    const defaultSuggestions = getDefaultSuggestions(code);
+    return {
+        code,
+        message,
+        retryable: options.retryable ?? isRetryableByDefault(code),
+        retryAfterMs: options.retryAfterMs,
+        suggestions: options.suggestions ?? defaultSuggestions,
+    };
+}
+/**
+ * Returns default suggestions for each error code.
+ */
+function getDefaultSuggestions(code) {
+    switch (code) {
+        case ErrorCode.AUTH_REQUIRED:
+            return ['Call teams_login to authenticate'];
+        case ErrorCode.AUTH_EXPIRED:
+            return ['Call teams_login to refresh authentication'];
+        case ErrorCode.RATE_LIMITED:
+            return ['Wait before retrying', 'Reduce request frequency'];
+        case ErrorCode.NOT_FOUND:
+            return ['Check the ID/query is correct', 'Verify the resource exists'];
+        case ErrorCode.INVALID_INPUT:
+            return ['Check the input parameters', 'Review the tool documentation'];
+        case ErrorCode.API_ERROR:
+            return ['Retry the request', 'Check teams_status for system health'];
+        case ErrorCode.BROWSER_ERROR:
+            return ['Call teams_login to restart browser session'];
+        case ErrorCode.NETWORK_ERROR:
+            return ['Check network connectivity', 'Retry the request'];
+        case ErrorCode.TIMEOUT:
+            return ['Retry the request', 'Use smaller page sizes'];
+        case ErrorCode.UNKNOWN:
+            return ['Check teams_status', 'Try teams_login if authentication issues'];
+    }
+}
+/**
+ * Determines if an error code is retryable by default.
+ */
+function isRetryableByDefault(code) {
+    switch (code) {
+        case ErrorCode.RATE_LIMITED:
+        case ErrorCode.NETWORK_ERROR:
+        case ErrorCode.TIMEOUT:
+        case ErrorCode.API_ERROR:
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * Classifies an HTTP status code into an error code.
+ */
+export function classifyHttpError(status, message) {
+    switch (status) {
+        case 401:
+            return ErrorCode.AUTH_EXPIRED;
+        case 403:
+            return ErrorCode.AUTH_REQUIRED;
+        case 404:
+            return ErrorCode.NOT_FOUND;
+        case 429:
+            return ErrorCode.RATE_LIMITED;
+        case 400:
+        case 422:
+            return ErrorCode.INVALID_INPUT;
+        default:
+            if (status >= 500)
+                return ErrorCode.API_ERROR;
+            if (message?.includes('timeout'))
+                return ErrorCode.TIMEOUT;
+            if (message?.includes('network') || message?.includes('ECONNRESET')) {
+                return ErrorCode.NETWORK_ERROR;
+            }
+            return ErrorCode.UNKNOWN;
+    }
+}
+/**
+ * Extracts retry-after value from response headers.
+ */
+export function extractRetryAfter(headers) {
+    const retryAfter = headers.get('Retry-After');
+    if (!retryAfter)
+        return undefined;
+    // Could be seconds (number) or HTTP date
+    const seconds = parseInt(retryAfter, 10);
+    if (!isNaN(seconds)) {
+        return seconds * 1000;
+    }
+    // Try parsing as HTTP date
+    try {
+        const date = new Date(retryAfter);
+        return Math.max(0, date.getTime() - Date.now());
+    }
+    catch {
+        return undefined;
+    }
+}