msteams-mcp 0.2.0

package/dist/research/explore.js

@@ -0,0 +1,267 @@
+/**
+ * Research script to explore Teams web app behaviour.
+ *
+ * This script:
+ * 1. Launches a browser with persistent context
+ * 2. Navigates to Teams and handles authentication
+ * 3. Monitors network requests to discover API endpoints
+ * 4. Allows manual interaction to trigger searches
+ * 5. Logs discovered endpoints and data structures
+ */
+import { chromium } from 'playwright';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, '../..');
+const USER_DATA_DIR = path.join(PROJECT_ROOT, '.user-data');
+const SESSION_STATE_PATH = path.join(PROJECT_ROOT, 'session-state.json');
+const FINDINGS_PATH = path.join(PROJECT_ROOT, 'research-findings.json');
+// Track interesting API calls
+const capturedNetworkData = {
+    requests: [],
+    responses: [],
+};
+// Patterns that indicate search-related API calls
+const SEARCH_PATTERNS = [
+    /search/i,
+    /query/i,
+    /find/i,
+    /substrate/i,
+    /graph\.microsoft/i,
+    /teams.*api/i,
+    /chatservice/i,
+    /emea\.ng\.msg/i,
+];
+function isInterestingUrl(url) {
+    // Skip static assets, telemetry, and auth-related noise
+    const skipPatterns = [
+        /\.(js|css|png|jpg|jpeg|gif|svg|woff|woff2|ttf|ico)(\?|$)/i,
+        /telemetry/i,
+        /analytics/i,
+        /logging/i,
+        /beacon/i,
+        /\.clarity\./i,
+        /fonts\./i,
+        /static/i,
+    ];
+    if (skipPatterns.some(pattern => pattern.test(url))) {
+        return false;
+    }
+    // Include if it matches search patterns or is a potential API call
+    return SEARCH_PATTERNS.some(pattern => pattern.test(url)) ||
+        url.includes('/api/') ||
+        url.includes('/v1/') ||
+        url.includes('/v2/');
+}
+async function captureRequest(request) {
+    const url = request.url();
+    if (!isInterestingUrl(url)) {
+        return;
+    }
+    const captured = {
+        url,
+        method: request.method(),
+        headers: request.headers(),
+        postData: request.postData() ?? undefined,
+        timestamp: new Date().toISOString(),
+        resourceType: request.resourceType(),
+    };
+    capturedNetworkData.requests.push(captured);
+    console.log(`\n📤 REQUEST: ${request.method()} ${url}`);
+    if (captured.postData) {
+        try {
+            const parsed = JSON.parse(captured.postData);
+            console.log('   Body:', JSON.stringify(parsed, null, 2).substring(0, 500));
+        }
+        catch {
+            console.log('   Body:', captured.postData.substring(0, 200));
+        }
+    }
+}
+async function captureResponse(response) {
+    const url = response.url();
+    if (!isInterestingUrl(url)) {
+        return;
+    }
+    let body;
+    try {
+        const contentType = response.headers()['content-type'] || '';
+        if (contentType.includes('application/json')) {
+            body = await response.text();
+        }
+    }
+    catch {
+        // Response body may not be available
+    }
+    const captured = {
+        url,
+        status: response.status(),
+        statusText: response.statusText(),
+        headers: response.headers(),
+        body,
+        timestamp: new Date().toISOString(),
+    };
+    capturedNetworkData.responses.push(captured);
+    console.log(`\n📥 RESPONSE: ${response.status()} ${url}`);
+    if (body) {
+        try {
+            const parsed = JSON.parse(body);
+            console.log('   Body preview:', JSON.stringify(parsed, null, 2).substring(0, 500));
+        }
+        catch {
+            console.log('   Body preview:', body.substring(0, 200));
+        }
+    }
+}
+async function saveFindings() {
+    // Deduplicate and summarise findings
+    const uniqueEndpoints = new Map();
+    for (const req of capturedNetworkData.requests) {
+        const key = `${req.method}:${new URL(req.url).pathname}`;
+        if (!uniqueEndpoints.has(key)) {
+            uniqueEndpoints.set(key, req);
+        }
+    }
+    const findings = {
+        discoveredAt: new Date().toISOString(),
+        uniqueEndpoints: Array.from(uniqueEndpoints.values()).map(req => ({
+            method: req.method,
+            url: req.url,
+            hasPostData: !!req.postData,
+            postDataSample: req.postData?.substring(0, 500),
+        })),
+        allRequests: capturedNetworkData.requests,
+        allResponses: capturedNetworkData.responses,
+    };
+    fs.writeFileSync(FINDINGS_PATH, JSON.stringify(findings, null, 2));
+    console.log(`\n💾 Findings saved to ${FINDINGS_PATH}`);
+}
+async function checkAuthentication(page) {
+    const url = page.url();
+    // Check if we're on a login page
+    if (url.includes('login.microsoftonline.com') ||
+        url.includes('login.live.com') ||
+        url.includes('login.microsoft.com')) {
+        return false;
+    }
+    // Check if we're on the Teams app
+    if (url.includes('teams.microsoft.com')) {
+        // Look for indicators that we're logged in
+        try {
+            // Wait briefly for the app to load
+            await page.waitForTimeout(2000);
+            // Check for common authenticated elements
+            const hasAppBar = await page.locator('[data-tid="app-bar"]').count() > 0;
+            const hasSearchBox = await page.locator('[data-tid="search-box"]').count() > 0 ||
+                await page.locator('input[placeholder*="Search"]').count() > 0;
+            return hasAppBar || hasSearchBox;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+async function waitForAuthentication(page) {
+    console.log('\n🔐 Please log in to Microsoft Teams in the browser window...');
+    console.log('   The script will continue once you are authenticated.\n');
+    // Poll for authentication
+    while (true) {
+        if (await checkAuthentication(page)) {
+            console.log('✅ Authentication detected!');
+            break;
+        }
+        await page.waitForTimeout(2000);
+    }
+}
+async function main() {
+    console.log('🔍 Teams Research Script');
+    console.log('========================\n');
+    console.log('This script will help discover how Teams web app works.\n');
+    // Ensure user data directory exists
+    if (!fs.existsSync(USER_DATA_DIR)) {
+        fs.mkdirSync(USER_DATA_DIR, { recursive: true });
+    }
+    let browser;
+    let context;
+    try {
+        // Launch browser with persistent context
+        browser = await chromium.launch({
+            headless: false, // Must be visible for manual login
+        });
+        // Check if we have saved session state
+        const hasSessionState = fs.existsSync(SESSION_STATE_PATH);
+        if (hasSessionState) {
+            console.log('📂 Found existing session state, attempting to restore...');
+            context = await browser.newContext({
+                storageState: SESSION_STATE_PATH,
+                viewport: { width: 1280, height: 800 },
+            });
+        }
+        else {
+            console.log('📂 No session state found, starting fresh...');
+            context = await browser.newContext({
+                viewport: { width: 1280, height: 800 },
+            });
+        }
+        const page = await context.newPage();
+        // Set up network interception
+        page.on('request', captureRequest);
+        page.on('response', captureResponse);
+        // Navigate to Teams
+        console.log('🌐 Navigating to Teams...');
+        await page.goto('https://teams.microsoft.com', { waitUntil: 'domcontentloaded' });
+        // Check if authentication is needed
+        const isAuthenticated = await checkAuthentication(page);
+        if (!isAuthenticated) {
+            await waitForAuthentication(page);
+            // Save session state after successful authentication
+            console.log('💾 Saving session state...');
+            await context.storageState({ path: SESSION_STATE_PATH });
+            console.log('✅ Session state saved!');
+        }
+        else {
+            console.log('✅ Already authenticated!');
+        }
+        // Instructions for the user
+        console.log('\n' + '='.repeat(60));
+        console.log('🔬 RESEARCH MODE ACTIVE');
+        console.log('='.repeat(60));
+        console.log('\nThe browser is now monitoring network requests.');
+        console.log('Try the following to discover API endpoints:\n');
+        console.log('1. Use the search bar (Cmd/Ctrl+E or click the search icon)');
+        console.log('2. Search for some text');
+        console.log('3. Click on search results');
+        console.log('4. Navigate between chats and channels');
+        console.log('\nPress Ctrl+C in this terminal when done to save findings.');
+        console.log('='.repeat(60) + '\n');
+        // Keep the browser open until interrupted
+        await new Promise((resolve) => {
+            process.on('SIGINT', () => {
+                console.log('\n\n⏹️  Stopping research...');
+                resolve();
+            });
+        });
+        // Save session state before closing
+        console.log('💾 Saving final session state...');
+        await context.storageState({ path: SESSION_STATE_PATH });
+        // Save research findings
+        await saveFindings();
+    }
+    catch (error) {
+        console.error('❌ Error:', error);
+        throw error;
+    }
+    finally {
+        if (context) {
+            await context.close();
+        }
+        if (browser) {
+            await browser.close();
+        }
+    }
+    console.log('\n✅ Research session complete!');
+    console.log(`   Review findings in: ${FINDINGS_PATH}`);
+}
+main().catch(console.error);

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

@@ -0,0 +1,17 @@
+/**
+ * Focused research script for Teams search API.
+ *
+ * Captures full request/response bodies for Substrate search endpoints
+ * to understand pagination, query format, and response structure.
+ *
+ * Usage:
+ *   npm run research:search
+ *
+ * Instructions:
+ *   1. Run this script
+ *   2. Perform a search in Teams
+ *   3. Click "Messages" tab or "See more results"
+ *   4. Scroll through results to trigger pagination
+ *   5. Press Ctrl+C to stop and save findings
+ */
+export {};

package/dist/research/search-research.js

@@ -0,0 +1,317 @@
+/**
+ * Focused research script for Teams search API.
+ *
+ * Captures full request/response bodies for Substrate search endpoints
+ * to understand pagination, query format, and response structure.
+ *
+ * Usage:
+ *   npm run research:search
+ *
+ * Instructions:
+ *   1. Run this script
+ *   2. Perform a search in Teams
+ *   3. Click "Messages" tab or "See more results"
+ *   4. Scroll through results to trigger pagination
+ *   5. Press Ctrl+C to stop and save findings
+ */
+import { chromium } from 'playwright';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, '../..');
+const SESSION_STATE_PATH = path.join(PROJECT_ROOT, 'session-state.json');
+const SEARCH_FINDINGS_PATH = path.join(PROJECT_ROOT, 'search-api-findings.json');
+const captures = [];
+// Focus specifically on search-related endpoints
+function isSearchEndpoint(url) {
+    const searchPatterns = [
+        /substrate\.office\.com\/search/i,
+        /\/api\/v\d+\/query/i,
+        /\/api\/v\d+\/suggestions/i,
+        /\/search\//i,
+    ];
+    return searchPatterns.some(p => p.test(url));
+}
+async function captureSearchRequest(request) {
+    const url = request.url();
+    if (!isSearchEndpoint(url))
+        return;
+    const postData = request.postData();
+    let body;
+    if (postData) {
+        try {
+            body = JSON.parse(postData);
+        }
+        catch {
+            body = postData;
+        }
+    }
+    const capture = {
+        timestamp: new Date().toISOString(),
+        type: 'request',
+        url,
+        method: request.method(),
+        body,
+        headers: request.headers(),
+    };
+    captures.push(capture);
+    console.log('\n' + '━'.repeat(80));
+    console.log(`📤 SEARCH REQUEST: ${request.method()} ${url}`);
+    console.log('━'.repeat(80));
+    if (body) {
+        console.log('\n📋 Request Body:');
+        console.log(JSON.stringify(body, null, 2));
+    }
+    // Highlight pagination-related fields
+    if (body && typeof body === 'object') {
+        const bodyObj = body;
+        const paginationFields = ['Size', 'From', 'Skip', 'Top', 'Offset', 'PageSize', 'Page', 'MaxResults'];
+        const foundPagination = {};
+        function findPaginationFields(obj, prefix = '') {
+            if (!obj || typeof obj !== 'object')
+                return;
+            for (const [key, value] of Object.entries(obj)) {
+                const fullKey = prefix ? `${prefix}.${key}` : key;
+                if (paginationFields.some(p => key.toLowerCase().includes(p.toLowerCase()))) {
+                    foundPagination[fullKey] = value;
+                }
+                if (typeof value === 'object') {
+                    findPaginationFields(value, fullKey);
+                }
+            }
+        }
+        findPaginationFields(bodyObj);
+        if (Object.keys(foundPagination).length > 0) {
+            console.log('\n📊 Pagination Fields Found:');
+            console.log(JSON.stringify(foundPagination, null, 2));
+        }
+    }
+}
+async function captureSearchResponse(response) {
+    const url = response.url();
+    if (!isSearchEndpoint(url))
+        return;
+    let body;
+    try {
+        const contentType = response.headers()['content-type'] || '';
+        if (contentType.includes('application/json')) {
+            const text = await response.text();
+            body = JSON.parse(text);
+        }
+    }
+    catch {
+        // Response body may not be available
+    }
+    const capture = {
+        timestamp: new Date().toISOString(),
+        type: 'response',
+        url,
+        status: response.status(),
+        body,
+    };
+    captures.push(capture);
+    console.log('\n' + '━'.repeat(80));
+    console.log(`📥 SEARCH RESPONSE: ${response.status()} ${url}`);
+    console.log('━'.repeat(80));
+    if (body && typeof body === 'object') {
+        const bodyObj = body;
+        // Show structure summary
+        console.log('\n📋 Response Structure:');
+        const summarise = (obj, depth = 0) => {
+            if (depth > 2)
+                return '...';
+            if (Array.isArray(obj)) {
+                return `Array[${obj.length}]${obj.length > 0 ? ` of ${summarise(obj[0], depth + 1)}` : ''}`;
+            }
+            if (obj && typeof obj === 'object') {
+                const keys = Object.keys(obj);
+                if (keys.length > 8) {
+                    return `{${keys.slice(0, 5).join(', ')}, ... +${keys.length - 5} more}`;
+                }
+                return `{${keys.join(', ')}}`;
+            }
+            return typeof obj;
+        };
+        console.log(summarise(bodyObj));
+        // Show pagination-related response fields
+        const paginationResponseFields = ['Total', 'TotalCount', 'Count', 'HasMore', 'HasNext', 'NextLink', 'SkipToken', 'ContinuationToken'];
+        const foundPagination = {};
+        function findPaginationFields(obj, prefix = '') {
+            if (!obj || typeof obj !== 'object')
+                return;
+            for (const [key, value] of Object.entries(obj)) {
+                const fullKey = prefix ? `${prefix}.${key}` : key;
+                if (paginationResponseFields.some(p => key.toLowerCase().includes(p.toLowerCase()))) {
+                    foundPagination[fullKey] = value;
+                }
+                if (typeof value === 'object' && !Array.isArray(value)) {
+                    findPaginationFields(value, fullKey);
+                }
+            }
+        }
+        findPaginationFields(bodyObj);
+        if (Object.keys(foundPagination).length > 0) {
+            console.log('\n📊 Pagination Response Fields:');
+            console.log(JSON.stringify(foundPagination, null, 2));
+        }
+        // Show results count
+        const countArrays = (obj) => {
+            const results = [];
+            function traverse(o, path) {
+                if (Array.isArray(o) && o.length > 0) {
+                    results.push({ path: path || 'root', count: o.length });
+                }
+                if (o && typeof o === 'object' && !Array.isArray(o)) {
+                    for (const [key, value] of Object.entries(o)) {
+                        traverse(value, path ? `${path}.${key}` : key);
+                    }
+                }
+            }
+            traverse(obj, '');
+            return results;
+        };
+        const arrays = countArrays(bodyObj);
+        if (arrays.length > 0) {
+            console.log('\n📈 Result Counts:');
+            arrays.forEach(a => console.log(`   ${a.path}: ${a.count} items`));
+        }
+        // Show first result sample if available
+        const findFirstResult = (obj) => {
+            if (Array.isArray(obj) && obj.length > 0) {
+                const first = obj[0];
+                if (first && typeof first === 'object' && Object.keys(first).length > 2) {
+                    return first;
+                }
+            }
+            if (obj && typeof obj === 'object') {
+                for (const value of Object.values(obj)) {
+                    const found = findFirstResult(value);
+                    if (found)
+                        return found;
+                }
+            }
+            return null;
+        };
+        const firstResult = findFirstResult(bodyObj);
+        if (firstResult) {
+            console.log('\n📄 First Result Sample:');
+            console.log(JSON.stringify(firstResult, null, 2).substring(0, 1000));
+        }
+    }
+}
+async function checkAuthentication(page) {
+    const url = page.url();
+    if (url.includes('login.microsoftonline.com') ||
+        url.includes('login.live.com') ||
+        url.includes('login.microsoft.com')) {
+        return false;
+    }
+    if (url.includes('teams.microsoft.com')) {
+        try {
+            await page.waitForTimeout(2000);
+            const hasAppBar = await page.locator('[data-tid="app-bar"]').count() > 0;
+            const hasSearchBox = await page.locator('[data-tid="search-box"]').count() > 0 ||
+                await page.locator('input[placeholder*="Search"]').count() > 0;
+            return hasAppBar || hasSearchBox;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+async function waitForAuthentication(page) {
+    console.log('\n🔐 Please log in to Microsoft Teams...');
+    while (true) {
+        if (await checkAuthentication(page)) {
+            console.log('✅ Authentication detected!');
+            break;
+        }
+        await page.waitForTimeout(2000);
+    }
+}
+async function saveFindings() {
+    const findings = {
+        capturedAt: new Date().toISOString(),
+        totalCaptures: captures.length,
+        requests: captures.filter(c => c.type === 'request'),
+        responses: captures.filter(c => c.type === 'response'),
+    };
+    fs.writeFileSync(SEARCH_FINDINGS_PATH, JSON.stringify(findings, null, 2));
+    console.log(`\n💾 Search findings saved to ${SEARCH_FINDINGS_PATH}`);
+}
+async function main() {
+    console.log('🔍 Teams Search API Research');
+    console.log('============================\n');
+    let browser;
+    let context;
+    try {
+        browser = await chromium.launch({ headless: false });
+        const hasSessionState = fs.existsSync(SESSION_STATE_PATH);
+        if (hasSessionState) {
+            console.log('📂 Restoring session state...');
+            context = await browser.newContext({
+                storageState: SESSION_STATE_PATH,
+                viewport: { width: 1400, height: 900 },
+            });
+        }
+        else {
+            console.log('📂 No session state found, starting fresh...');
+            context = await browser.newContext({
+                viewport: { width: 1400, height: 900 },
+            });
+        }
+        const page = await context.newPage();
+        // Set up network interception for search endpoints only
+        page.on('request', captureSearchRequest);
+        page.on('response', captureSearchResponse);
+        console.log('🌐 Navigating to Teams...');
+        await page.goto('https://teams.microsoft.com', { waitUntil: 'domcontentloaded' });
+        const isAuthenticated = await checkAuthentication(page);
+        if (!isAuthenticated) {
+            await waitForAuthentication(page);
+            await context.storageState({ path: SESSION_STATE_PATH });
+            console.log('✅ Session state saved!');
+        }
+        else {
+            console.log('✅ Already authenticated!');
+        }
+        console.log('\n' + '═'.repeat(60));
+        console.log('🔬 SEARCH RESEARCH MODE');
+        console.log('═'.repeat(60));
+        console.log('\nTo capture search API data:');
+        console.log('');
+        console.log('  1. Press Cmd/Ctrl+E to open search');
+        console.log('  2. Type a search query and press Enter');
+        console.log('  3. Click "Messages" tab to see message results');
+        console.log('  4. Click "See all results" if available');
+        console.log('  5. Scroll through results to trigger pagination');
+        console.log('');
+        console.log('Watch for 📊 Pagination Fields in the output!');
+        console.log('');
+        console.log('Press Ctrl+C when done to save findings.');
+        console.log('═'.repeat(60) + '\n');
+        await new Promise((resolve) => {
+            process.on('SIGINT', () => {
+                console.log('\n\n⏹️  Stopping research...');
+                resolve();
+            });
+        });
+        await context.storageState({ path: SESSION_STATE_PATH });
+        await saveFindings();
+    }
+    catch (error) {
+        console.error('❌ Error:', error);
+        throw error;
+    }
+    finally {
+        if (context)
+            await context.close();
+        if (browser)
+            await browser.close();
+    }
+    console.log('\n✅ Search research complete!');
+    console.log(`   Review findings in: ${SEARCH_FINDINGS_PATH}`);
+}
+main().catch(console.error);

package/dist/server.d.ts

@@ -0,0 +1,64 @@
+/**
+ * MCP Server implementation for Teams search.
+ * Exposes tools and resources for interacting with Microsoft Teams.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type BrowserManager } from './browser/context.js';
+/**
+ * MCP Server for Teams integration.
+ *
+ * Encapsulates all server state to allow multiple instances.
+ */
+export declare class TeamsServer {
+    private browserManager;
+    private isInitialised;
+    /**
+     * Returns a standard MCP error response.
+     */
+    private formatError;
+    /**
+     * Returns a standard MCP success response.
+     */
+    private formatSuccess;
+    /**
+     * Gets the current browser manager.
+     */
+    getBrowserManager(): BrowserManager | null;
+    /**
+     * Sets the browser manager.
+     */
+    setBrowserManager(manager: BrowserManager): void;
+    /**
+     * Resets browser state.
+     */
+    resetBrowserState(): void;
+    /**
+     * Marks the server as initialised.
+     */
+    markInitialised(): void;
+    /**
+     * Checks if the server is initialised.
+     */
+    isInitialisedState(): boolean;
+    /**
+     * Ensures the browser is running and authenticated.
+     */
+    ensureBrowser(headless?: boolean): Promise<BrowserManager>;
+    /**
+     * Cleans up browser resources.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Creates and configures the MCP server.
+     */
+    createServer(): Promise<Server>;
+}
+/**
+ * Creates and runs the MCP server.
+ * Exported for backward compatibility.
+ */
+export declare function createServer(): Promise<Server>;
+/**
+ * Runs the server with stdio transport.
+ */
+export declare function runServer(): Promise<void>;