msteams-mcp 0.2.0

package/dist/test/mcp-harness.js

@@ -0,0 +1,427 @@
+#!/usr/bin/env npx tsx
+/**
+ * MCP Protocol Test Harness
+ *
+ * Tests the MCP server by connecting a client through the actual MCP protocol,
+ * rather than calling underlying functions directly. This ensures the full
+ * protocol layer works correctly.
+ *
+ * Usage:
+ *   npm run test:mcp                              # List tools and check status
+ *   npm run test:mcp -- search "query"            # Search for messages (shortcut)
+ *   npm run test:mcp -- teams_search --query "q"  # Generic tool call
+ *   npm run test:mcp -- --json                    # Output as JSON
+ *
+ * Any unrecognised command is treated as a tool name. Use --key value for parameters.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { createServer } from '../server.js';
+// Shortcuts map command names to tool names and parameter mappings
+const SHORTCUTS = {
+    search: { tool: 'teams_search', primaryArg: 'query' },
+    status: { tool: 'teams_status' },
+    send: { tool: 'teams_send_message', primaryArg: 'content' },
+    reply: { tool: 'teams_reply_to_thread', primaryArg: 'content' },
+    me: { tool: 'teams_get_me' },
+    people: { tool: 'teams_search_people', primaryArg: 'query' },
+    favorites: { tool: 'teams_get_favorites' },
+    save: { tool: 'teams_save_message' },
+    unsave: { tool: 'teams_unsave_message' },
+    thread: { tool: 'teams_get_thread' },
+    login: { tool: 'teams_login' },
+    contacts: { tool: 'teams_get_frequent_contacts' },
+    channel: { tool: 'teams_find_channel', primaryArg: 'query' },
+    chat: { tool: 'teams_get_chat', primaryArg: 'userId' },
+};
+// Map CLI flags to tool parameter names
+const FLAG_MAPPINGS = {
+    '--to': 'conversationId',
+    '--message': 'messageId',
+    '--reply': 'replyToMessageId',
+    '--replyTo': 'replyToMessageId',
+    '--from': 'from',
+    '--size': 'size',
+    '--limit': 'limit',
+    '--query': 'query',
+    '--content': 'content',
+    '--force': 'forceNew',
+    '--user': 'userId',
+    '--userId': 'userId',
+};
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {
+        command: 'list',
+        toolName: null,
+        primaryArg: null,
+        args: {},
+        json: false,
+    };
+    let i = 0;
+    // First pass: find the command (first non-flag argument)
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === '--json') {
+            result.json = true;
+            i++;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            // Skip flag and its value
+            i += 2;
+            continue;
+        }
+        // Found the command
+        result.command = arg;
+        i++;
+        break;
+    }
+    // Check if it's a shortcut
+    const shortcut = SHORTCUTS[result.command];
+    if (shortcut) {
+        result.toolName = shortcut.tool;
+        // Look for primary argument (next non-flag arg)
+        while (i < args.length) {
+            const arg = args[i];
+            if (!arg.startsWith('--')) {
+                if (shortcut.primaryArg) {
+                    result.args[shortcut.primaryArg] = arg;
+                }
+                result.primaryArg = arg;
+                i++;
+                break;
+            }
+            i++;
+        }
+    }
+    else if (result.command !== 'list') {
+        // Treat as a tool name (add teams_ prefix if not present)
+        result.toolName = result.command.startsWith('teams_')
+            ? result.command
+            : `teams_${result.command}`;
+    }
+    // Second pass: collect all --key value pairs
+    for (let j = 0; j < args.length; j++) {
+        const arg = args[j];
+        if (arg === '--json') {
+            result.json = true;
+            continue;
+        }
+        if (arg.startsWith('--') && args[j + 1] !== undefined) {
+            const key = FLAG_MAPPINGS[arg] || arg.slice(2); // Use mapping or strip --
+            let value = args[j + 1];
+            // Try to parse as number or boolean
+            if (value === 'true')
+                value = true;
+            else if (value === 'false')
+                value = false;
+            else if (/^\d+$/.test(value))
+                value = parseInt(value, 10);
+            result.args[key] = value;
+            j++; // Skip the value
+        }
+    }
+    return result;
+}
+function log(message) {
+    console.log(message);
+}
+function logSection(title) {
+    console.log('\n' + '─'.repeat(50));
+    console.log(`  ${title}`);
+    console.log('─'.repeat(50));
+}
+async function createTestClient() {
+    // Create the MCP server
+    const server = await createServer();
+    // Create linked in-memory transports
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    // Connect the server to its transport
+    await server.connect(serverTransport);
+    // Create and connect the client
+    const client = new Client({ name: 'mcp-test-harness', version: '1.0.0' }, { capabilities: {} });
+    await client.connect(clientTransport);
+    const cleanup = async () => {
+        await client.close();
+        await server.close();
+    };
+    return { client, cleanup };
+}
+async function listTools(client, json) {
+    if (!json) {
+        logSection('Available Tools');
+    }
+    const result = await client.listTools();
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    log(`Found ${result.tools.length} tools:\n`);
+    for (const tool of result.tools) {
+        log(`📦 ${tool.name}`);
+        log(`   ${tool.description}`);
+        const schema = tool.inputSchema;
+        if (schema.properties) {
+            const props = Object.entries(schema.properties);
+            const required = new Set(schema.required ?? []);
+            for (const [name, prop] of props) {
+                const propObj = prop;
+                const reqMark = required.has(name) ? ' (required)' : '';
+                log(`   - ${name}: ${propObj.type ?? 'any'}${reqMark}`);
+                if (propObj.description) {
+                    log(`     ${propObj.description}`);
+                }
+            }
+        }
+        log('');
+    }
+    // Show available shortcuts
+    log('Shortcuts:');
+    for (const [shortcut, config] of Object.entries(SHORTCUTS)) {
+        const primaryNote = config.primaryArg ? ` <${config.primaryArg}>` : '';
+        log(`  ${shortcut}${primaryNote} → ${config.tool}`);
+    }
+    log('');
+    log('Any unrecognised command is treated as a tool name.');
+    log('Use --key value for parameters, e.g.: teams_find_channel --query "name"');
+}
+async function callTool(client, toolName, args, json) {
+    // Verify the tool exists
+    const tools = await client.listTools();
+    const tool = tools.tools.find(t => t.name === toolName);
+    if (!tool) {
+        console.error(`❌ Unknown tool: ${toolName}`);
+        console.error('');
+        console.error('Available tools:');
+        for (const t of tools.tools) {
+            console.error(`  - ${t.name}`);
+        }
+        process.exit(1);
+    }
+    if (!json) {
+        logSection(`Calling: ${toolName}`);
+        if (Object.keys(args).length > 0) {
+            log(`Arguments: ${JSON.stringify(args)}\n`);
+        }
+    }
+    const result = await client.callTool({ name: toolName, arguments: args });
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // Pretty-print the result
+    const content = result.content;
+    const textContent = content.find(c => c.type === 'text');
+    if (textContent?.text) {
+        try {
+            const response = JSON.parse(textContent.text);
+            prettyPrintResponse(response, toolName);
+        }
+        catch {
+            // Not JSON, just print as-is
+            log(textContent.text);
+        }
+    }
+    else {
+        log('(No text content in response)');
+    }
+}
+/**
+ * Pretty-prints a tool response based on common patterns
+ */
+function prettyPrintResponse(response, toolName) {
+    // Check for error
+    if (response.success === false) {
+        log(`❌ Failed: ${response.error || 'Unknown error'}`);
+        if (response.code)
+            log(`   Code: ${response.code}`);
+        if (response.suggestion)
+            log(`   Suggestion: ${response.suggestion}`);
+        return;
+    }
+    log('✅ Success\n');
+    // Handle common response shapes
+    if (response.results && Array.isArray(response.results)) {
+        printResultsList(response.results, response);
+    }
+    else if (response.favorites && Array.isArray(response.favorites)) {
+        printFavoritesList(response.favorites);
+    }
+    else if (response.messages && Array.isArray(response.messages)) {
+        printMessagesList(response.messages);
+    }
+    else if (response.contacts && Array.isArray(response.contacts)) {
+        printContactsList(response.contacts);
+    }
+    else if (response.profile) {
+        printProfile(response.profile);
+    }
+    else {
+        // Generic output for other responses
+        printGenericResponse(response);
+    }
+    // Print pagination if present
+    if (response.pagination) {
+        const p = response.pagination;
+        log(`\nPagination: from=${p.from}, size=${p.size}, returned=${p.returned}`);
+        if (p.total !== undefined)
+            log(`Total available: ${p.total}`);
+        if (p.hasMore)
+            log(`More results available (use --from ${p.nextFrom})`);
+    }
+}
+function printResultsList(results, response) {
+    log(`Found ${response.resultCount ?? results.length} results:\n`);
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const num = (response.pagination?.from ?? 0) + i + 1;
+        // Try to extract meaningful content
+        const content = String(r.content ?? r.displayName ?? r.name ?? '').substring(0, 100).replace(/\n/g, ' ');
+        log(`${num}. ${content}${content.length >= 100 ? '...' : ''}`);
+        // Print common fields
+        const sender = extractSenderName(r.sender);
+        if (sender)
+            log(`   From: ${sender}`);
+        if (r.email)
+            log(`   Email: ${r.email}`);
+        if (r.teamName)
+            log(`   Team: ${r.teamName}`);
+        if (r.channelName && r.channelName !== r.teamName)
+            log(`   Channel: ${r.channelName}`);
+        if (r.timestamp)
+            log(`   Time: ${r.timestamp}`);
+        if (r.conversationId)
+            log(`   ConversationId: ${r.conversationId}`);
+        if (r.jobTitle)
+            log(`   Title: ${r.jobTitle}`);
+        if (r.department)
+            log(`   Dept: ${r.department}`);
+        if (r.mri)
+            log(`   MRI: ${r.mri}`);
+        log('');
+    }
+}
+function printFavoritesList(favorites) {
+    log(`Found ${favorites.length} favourites:\n`);
+    for (const f of favorites) {
+        const fav = f;
+        const typeLabel = fav.conversationType ? ` [${fav.conversationType}]` : '';
+        const nameLabel = fav.displayName || '(unnamed)';
+        log(`⭐ ${nameLabel}${typeLabel}`);
+        log(`   ID: ${fav.conversationId}`);
+    }
+}
+function printMessagesList(messages) {
+    log(`Got ${messages.length} messages:\n`);
+    for (const msg of messages) {
+        const m = msg;
+        const preview = String(m.content ?? '').substring(0, 100).replace(/\n/g, ' ');
+        const sender = m.sender?.displayName ||
+            m.sender?.mri || 'Unknown';
+        const time = m.timestamp ? new Date(m.timestamp).toLocaleString() : '';
+        const fromMe = m.isFromMe ? ' (you)' : '';
+        log(`📝 ${sender}${fromMe} - ${time}`);
+        log(`   ${preview}${String(m.content ?? '').length > 100 ? '...' : ''}`);
+        log('');
+    }
+}
+function printContactsList(contacts) {
+    log(`Found ${contacts.length} contacts:\n`);
+    for (const c of contacts) {
+        const contact = c;
+        log(`👤 ${contact.displayName}`);
+        if (contact.email)
+            log(`   Email: ${contact.email}`);
+        if (contact.jobTitle)
+            log(`   Title: ${contact.jobTitle}`);
+        if (contact.department)
+            log(`   Dept: ${contact.department}`);
+        log('');
+    }
+}
+function printProfile(profile) {
+    log('👤 Profile:\n');
+    for (const [key, value] of Object.entries(profile)) {
+        if (value !== null && value !== undefined) {
+            log(`   ${key}: ${value}`);
+        }
+    }
+}
+function printGenericResponse(response) {
+    // Filter out success flag and print remaining fields
+    for (const [key, value] of Object.entries(response)) {
+        if (key === 'success')
+            continue;
+        if (typeof value === 'object' && value !== null) {
+            log(`${key}: ${JSON.stringify(value, null, 2)}`);
+        }
+        else {
+            log(`${key}: ${value}`);
+        }
+    }
+}
+function extractSenderName(sender) {
+    if (!sender)
+        return null;
+    if (typeof sender === 'string')
+        return sender;
+    if (typeof sender === 'object') {
+        const s = sender;
+        // Handle { EmailAddress: { Name: string } } structure
+        if (s.EmailAddress && typeof s.EmailAddress === 'object') {
+            const email = s.EmailAddress;
+            if (email.Name)
+                return String(email.Name);
+            if (email.Address)
+                return String(email.Address);
+        }
+        // Handle { name: string } or { displayName: string } structure
+        if (s.displayName)
+            return String(s.displayName);
+        if (s.name)
+            return String(s.name);
+        if (s.Name)
+            return String(s.Name);
+    }
+    return null;
+}
+async function main() {
+    const parsed = parseArgs();
+    if (!parsed.json) {
+        console.log('\n🧪 MCP Protocol Test Harness');
+        console.log('============================');
+    }
+    let cleanup = null;
+    try {
+        const { client, cleanup: cleanupFn } = await createTestClient();
+        cleanup = cleanupFn;
+        if (!parsed.json) {
+            log('\n✅ Connected to MCP server via in-memory transport');
+        }
+        if (parsed.command === 'list' || !parsed.toolName) {
+            await listTools(client, parsed.json);
+        }
+        else {
+            await callTool(client, parsed.toolName, parsed.args, parsed.json);
+        }
+        if (!parsed.json) {
+            logSection('Complete');
+            log('MCP protocol test finished successfully.');
+        }
+    }
+    catch (error) {
+        console.error('\n❌ Error:', error instanceof Error ? error.message : String(error));
+        if (error instanceof Error && error.stack) {
+            console.error('\nStack trace:');
+            console.error(error.stack);
+        }
+        process.exit(1);
+    }
+    finally {
+        if (cleanup) {
+            await cleanup();
+        }
+    }
+}
+main();

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

@@ -0,0 +1,26 @@
+/**
+ * Authentication-related tool handlers.
+ */
+import { z } from 'zod';
+import type { RegisteredTool } from './index.js';
+export declare const LoginInputSchema: z.ZodObject<{
+    forceNew: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    forceNew: boolean;
+}, {
+    forceNew?: boolean | undefined;
+}>;
+export declare const loginTool: RegisteredTool<typeof LoginInputSchema>;
+export declare const statusTool: RegisteredTool<z.ZodObject<Record<string, never>>>;
+/** All auth-related tools. */
+export declare const authTools: (RegisteredTool<z.ZodObject<Record<string, never>, z.UnknownKeysParam, z.ZodTypeAny, {
+    [x: string]: never;
+}, {
+    [x: string]: never;
+}>> | RegisteredTool<z.ZodObject<{
+    forceNew: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    forceNew: boolean;
+}, {
+    forceNew?: boolean | undefined;
+}>>)[];

package/dist/tools/auth-tools.js

@@ -0,0 +1,127 @@
+/**
+ * Authentication-related tool handlers.
+ */
+import { z } from 'zod';
+import { hasSessionState, isSessionLikelyExpired, clearSessionState, } from '../auth/session-store.js';
+import { getSubstrateTokenStatus, extractMessageAuth, extractCsaToken, clearTokenCache, } from '../auth/token-extractor.js';
+import { createBrowserContext, closeBrowser } from '../browser/context.js';
+import { ensureAuthenticated, forceNewLogin, getAuthStatus } from '../browser/auth.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Schemas
+// ─────────────────────────────────────────────────────────────────────────────
+export const LoginInputSchema = z.object({
+    forceNew: z.boolean().optional().default(false),
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Definitions
+// ─────────────────────────────────────────────────────────────────────────────
+const loginToolDefinition = {
+    name: 'teams_login',
+    description: 'Trigger manual login flow for Microsoft Teams. Use this if the session has expired or you need to switch accounts.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            forceNew: {
+                type: 'boolean',
+                description: 'Force a new login even if a session exists (default: false)',
+            },
+        },
+    },
+};
+const statusToolDefinition = {
+    name: 'teams_status',
+    description: 'Check the current authentication status and session state.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Handlers
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleLogin(input, ctx) {
+    // Close existing browser if any
+    const existingManager = ctx.server.getBrowserManager();
+    if (existingManager) {
+        await closeBrowser(existingManager, !input.forceNew);
+        ctx.server.resetBrowserState();
+    }
+    if (input.forceNew) {
+        clearSessionState();
+        clearTokenCache();
+    }
+    const browserManager = await createBrowserContext({ headless: false });
+    ctx.server.setBrowserManager(browserManager);
+    try {
+        if (input.forceNew) {
+            await forceNewLogin(browserManager.page, browserManager.context, (msg) => console.error(`[login] ${msg}`));
+        }
+        else {
+            await ensureAuthenticated(browserManager.page, browserManager.context, (msg) => console.error(`[login] ${msg}`));
+        }
+    }
+    finally {
+        // Close browser after login - we only need the saved session/tokens
+        await closeBrowser(browserManager, true);
+        ctx.server.resetBrowserState();
+    }
+    ctx.server.markInitialised();
+    return {
+        success: true,
+        data: {
+            message: 'Login completed successfully. Session has been saved.',
+        },
+    };
+}
+async function handleStatus(_input, ctx) {
+    const sessionExists = hasSessionState();
+    const sessionExpired = isSessionLikelyExpired();
+    const tokenStatus = getSubstrateTokenStatus();
+    const messageAuth = extractMessageAuth();
+    const csaToken = extractCsaToken();
+    let authStatus = null;
+    const browserManager = ctx.server.getBrowserManager();
+    if (browserManager && ctx.server.isInitialisedState()) {
+        authStatus = await getAuthStatus(browserManager.page);
+    }
+    return {
+        success: true,
+        data: {
+            directApi: {
+                available: tokenStatus.hasToken,
+                expiresAt: tokenStatus.expiresAt,
+                minutesRemaining: tokenStatus.minutesRemaining,
+            },
+            messaging: {
+                available: messageAuth !== null,
+            },
+            favorites: {
+                available: messageAuth !== null && csaToken !== null,
+            },
+            session: {
+                exists: sessionExists,
+                likelyExpired: sessionExpired,
+            },
+            browser: {
+                running: browserManager !== null,
+                initialised: ctx.server.isInitialisedState(),
+            },
+            authentication: authStatus,
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────────────────────
+export const loginTool = {
+    definition: loginToolDefinition,
+    schema: LoginInputSchema,
+    handler: handleLogin,
+};
+export const statusTool = {
+    definition: statusToolDefinition,
+    schema: z.object({}),
+    handler: handleStatus,
+};
+/** All auth-related tools. */
+export const authTools = [loginTool, statusTool];

package/dist/tools/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Tool handler registry.
+ *
+ * Provides a modular way to define MCP tool handlers without a monolithic
+ * switch statement. Each tool is defined with its schema, handler, and metadata.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { z } from 'zod';
+import type { McpError } from '../types/errors.js';
+import type { BrowserManager } from '../browser/context.js';
+export interface TeamsServer {
+    ensureBrowser(headless?: boolean): Promise<BrowserManager>;
+    resetBrowserState(): void;
+    getBrowserManager(): BrowserManager | null;
+    setBrowserManager(manager: BrowserManager): void;
+    markInitialised(): void;
+    isInitialisedState(): boolean;
+}
+/** The context passed to tool handlers. */
+export interface ToolContext {
+    /** Reference to the server for browser operations. */
+    server: TeamsServer;
+}
+/** Result returned by tool handlers. */
+export type ToolResult = {
+    success: true;
+    data: Record<string, unknown>;
+} | {
+    success: false;
+    error: McpError;
+};
+/** A registered tool with its handler. */
+export interface RegisteredTool<TInput extends z.ZodType = z.ZodType> {
+    /** Tool definition for MCP. */
+    definition: Tool;
+    /** Zod schema for input validation. */
+    schema: TInput;
+    /** Handler function. */
+    handler: (input: z.infer<TInput>, ctx: ToolContext) => Promise<ToolResult>;
+}
+export * from './search-tools.js';
+export * from './message-tools.js';
+export * from './people-tools.js';
+export * from './auth-tools.js';
+export * from './registry.js';

package/dist/tools/index.js

@@ -0,0 +1,12 @@
+/**
+ * Tool handler registry.
+ *
+ * Provides a modular way to define MCP tool handlers without a monolithic
+ * switch statement. Each tool is defined with its schema, handler, and metadata.
+ */
+// Re-export tool registrations
+export * from './search-tools.js';
+export * from './message-tools.js';
+export * from './people-tools.js';
+export * from './auth-tools.js';
+export * from './registry.js';