msteams-mcp 0.2.0

package/dist/api/csa-api.js

@@ -0,0 +1,148 @@
+/**
+ * CSA (Chat Service Aggregator) API client for favorites and teams operations.
+ *
+ * Handles all calls to teams.microsoft.com/api/csa endpoints.
+ */
+import { httpRequest } from '../utils/http.js';
+import { CSA_API, getCsaHeaders, validateRegion } from '../utils/api-config.js';
+import { ErrorCode, createError } from '../types/errors.js';
+import { ok, err } from '../types/result.js';
+import { requireCsaAuth } from '../utils/auth-guards.js';
+import { getConversationProperties, extractParticipantNames, } from './chatsvc-api.js';
+import { parseTeamsList, } from '../utils/parsers.js';
+/**
+ * Gets the user's favourite/pinned conversations.
+ */
+export async function getFavorites(region = 'amer') {
+    const authResult = requireCsaAuth();
+    if (!authResult.ok) {
+        return authResult;
+    }
+    const { auth, csaToken } = authResult.value;
+    const validRegion = validateRegion(region);
+    const url = CSA_API.conversationFolders(validRegion);
+    const response = await httpRequest(url, {
+        method: 'GET',
+        headers: getCsaHeaders(auth.skypeToken, csaToken),
+    });
+    if (!response.ok) {
+        return response;
+    }
+    const data = response.value.data;
+    // Find the Favorites folder
+    const folders = data.conversationFolders;
+    const favoritesFolder = folders?.find((f) => {
+        const folder = f;
+        return folder.folderType === 'Favorites';
+    });
+    if (!favoritesFolder) {
+        return ok({
+            favorites: [],
+            folderHierarchyVersion: data.folderHierarchyVersion,
+        });
+    }
+    const items = favoritesFolder.conversationFolderItems;
+    const favorites = (items || []).map((item) => {
+        const i = item;
+        return {
+            conversationId: i.conversationId,
+            createdTime: i.createdTime,
+            lastUpdatedTime: i.lastUpdatedTime,
+        };
+    });
+    // Enrich favorites with display names in parallel
+    const enrichmentPromises = favorites.map(async (fav) => {
+        const props = await getConversationProperties(fav.conversationId, validRegion);
+        if (props.ok) {
+            fav.displayName = props.value.displayName;
+            fav.conversationType = props.value.conversationType;
+        }
+        // Fallback: extract from recent messages if no display name
+        if (!fav.displayName) {
+            const names = await extractParticipantNames(fav.conversationId, validRegion);
+            if (names.ok && names.value) {
+                fav.displayName = names.value;
+            }
+        }
+    });
+    await Promise.allSettled(enrichmentPromises);
+    return ok({
+        favorites,
+        folderHierarchyVersion: data.folderHierarchyVersion,
+        folderId: favoritesFolder.id,
+    });
+}
+/**
+ * Adds a conversation to the user's favourites.
+ */
+export async function addFavorite(conversationId, region = 'amer') {
+    return modifyFavorite(conversationId, 'AddItem', region);
+}
+/**
+ * Removes a conversation from the user's favourites.
+ */
+export async function removeFavorite(conversationId, region = 'amer') {
+    return modifyFavorite(conversationId, 'RemoveItem', region);
+}
+/**
+ * Internal helper to modify the favourites folder.
+ */
+async function modifyFavorite(conversationId, action, region) {
+    const authResult = requireCsaAuth();
+    if (!authResult.ok) {
+        return authResult;
+    }
+    const { auth, csaToken } = authResult.value;
+    const validRegion = validateRegion(region);
+    // Get current folder state
+    const currentState = await getFavorites(validRegion);
+    if (!currentState.ok) {
+        return err(currentState.error);
+    }
+    if (!currentState.value.folderId) {
+        return err(createError(ErrorCode.NOT_FOUND, 'Could not find Favorites folder'));
+    }
+    const url = CSA_API.conversationFolders(validRegion);
+    const response = await httpRequest(url, {
+        method: 'POST',
+        headers: getCsaHeaders(auth.skypeToken, csaToken),
+        body: JSON.stringify({
+            folderHierarchyVersion: currentState.value.folderHierarchyVersion,
+            actions: [
+                {
+                    action,
+                    folderId: currentState.value.folderId,
+                    itemId: conversationId,
+                },
+            ],
+        }),
+    });
+    if (!response.ok) {
+        return response;
+    }
+    return ok(undefined);
+}
+/**
+ * Gets all teams and channels the user is a member of.
+ *
+ * This returns the complete list of teams with their channels - not a search,
+ * but a full enumeration of the user's memberships.
+ */
+export async function getMyTeamsAndChannels(region = 'amer') {
+    const authResult = requireCsaAuth();
+    if (!authResult.ok) {
+        return authResult;
+    }
+    const { auth, csaToken } = authResult.value;
+    const validRegion = validateRegion(region);
+    const url = CSA_API.teamsList(validRegion);
+    const response = await httpRequest(url, {
+        method: 'GET',
+        headers: getCsaHeaders(auth.skypeToken, csaToken),
+    });
+    if (!response.ok) {
+        return response;
+    }
+    const teams = parseTeamsList(response.value.data);
+    return ok({ teams });
+}

package/dist/api/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * API module exports.
+ */
+export * from './substrate-api.js';
+export * from './chatsvc-api.js';
+export * from './csa-api.js';

package/dist/api/index.js

@@ -0,0 +1,6 @@
+/**
+ * API module exports.
+ */
+export * from './substrate-api.js';
+export * from './chatsvc-api.js';
+export * from './csa-api.js';

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

@@ -0,0 +1,50 @@
+/**
+ * Substrate API client for search and people operations.
+ *
+ * Handles all calls to substrate.office.com endpoints.
+ */
+import { type Result } from '../types/result.js';
+import { type PersonSearchResult, type ChannelSearchResult } from '../utils/parsers.js';
+import type { TeamsSearchResult, SearchPaginationResult } from '../types/teams.js';
+/** Search result with pagination. */
+export interface SearchResult {
+    results: TeamsSearchResult[];
+    pagination: SearchPaginationResult;
+}
+/** People search result. */
+export interface PeopleSearchResult {
+    results: PersonSearchResult[];
+    returned: number;
+}
+/**
+ * Searches Teams messages using the Substrate v2 query API.
+ */
+export declare function searchMessages(query: string, options?: {
+    from?: number;
+    size?: number;
+    maxResults?: number;
+}): Promise<Result<SearchResult>>;
+/**
+ * Searches for people by name or email.
+ */
+export declare function searchPeople(query: string, limit?: number): Promise<Result<PeopleSearchResult>>;
+/**
+ * Gets the user's frequently contacted people.
+ */
+export declare function getFrequentContacts(limit?: number): Promise<Result<PeopleSearchResult>>;
+/** Channel search result. */
+export interface ChannelSearchResultSet {
+    results: ChannelSearchResult[];
+    returned: number;
+}
+/**
+ * Searches for Teams channels by name using both:
+ * 1. User's own teams/channels (Teams List API) - reliable, shows membership
+ * 2. Organisation-wide discovery (Substrate suggestions) - broader but less reliable
+ *
+ * Results are merged and deduplicated, with membership status indicated.
+ *
+ * @param query - Channel name to search for
+ * @param limit - Maximum number of results (default: 10, max: 50)
+ */
+export declare function searchChannels(query: string, limit?: number): Promise<Result<ChannelSearchResultSet>>;

package/dist/api/substrate-api.js

@@ -0,0 +1,305 @@
+/**
+ * Substrate API client for search and people operations.
+ *
+ * Handles all calls to substrate.office.com endpoints.
+ */
+import { httpRequest } from '../utils/http.js';
+import { SUBSTRATE_API, getBearerHeaders } from '../utils/api-config.js';
+import { ErrorCode } from '../types/errors.js';
+import { ok } from '../types/result.js';
+import { clearTokenCache } from '../auth/token-extractor.js';
+import { requireSubstrateToken } from '../utils/auth-guards.js';
+import { parseSearchResults, parsePeopleResults, parseChannelResults, filterChannelsByName, } from '../utils/parsers.js';
+import { getMyTeamsAndChannels } from './csa-api.js';
+/**
+ * Searches Teams messages using the Substrate v2 query API.
+ */
+export async function searchMessages(query, options = {}) {
+    const tokenResult = requireSubstrateToken();
+    if (!tokenResult.ok) {
+        return tokenResult;
+    }
+    const token = tokenResult.value;
+    const from = options.from ?? 0;
+    const size = options.size ?? 25;
+    // Generate unique IDs for this request
+    const cvid = crypto.randomUUID();
+    const logicalId = crypto.randomUUID();
+    const body = {
+        entityRequests: [{
+                entityType: 'Message',
+                contentSources: ['Teams'],
+                propertySet: 'Optimized',
+                fields: [
+                    'Extension_SkypeSpaces_ConversationPost_Extension_FromSkypeInternalId_String',
+                    'Extension_SkypeSpaces_ConversationPost_Extension_ThreadType_String',
+                    'Extension_SkypeSpaces_ConversationPost_Extension_SkypeGroupId_String',
+                ],
+                query: {
+                    queryString: `${query} AND NOT (isClientSoftDeleted:TRUE)`,
+                    displayQueryString: query,
+                },
+                from,
+                size,
+                topResultsCount: 5,
+            }],
+        QueryAlterationOptions: {
+            EnableAlteration: true,
+            EnableSuggestion: true,
+            SupportedRecourseDisplayTypes: ['Suggestion'],
+        },
+        cvid,
+        logicalId,
+        scenario: {
+            Dimensions: [
+                { DimensionName: 'QueryType', DimensionValue: 'Messages' },
+                { DimensionName: 'FormFactor', DimensionValue: 'general.web.reactSearch' },
+            ],
+            Name: 'powerbar',
+        },
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    };
+    const response = await httpRequest(SUBSTRATE_API.search, {
+        method: 'POST',
+        headers: getBearerHeaders(token),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        // Clear cache on auth errors
+        if (response.error.code === ErrorCode.AUTH_EXPIRED) {
+            clearTokenCache();
+        }
+        return response;
+    }
+    const data = response.value.data;
+    const { results, total } = parseSearchResults(data.EntitySets, from, size);
+    const maxResults = options.maxResults ?? size;
+    const limitedResults = results.slice(0, maxResults);
+    return ok({
+        results: limitedResults,
+        pagination: {
+            from,
+            size,
+            returned: limitedResults.length,
+            total,
+            hasMore: total !== undefined
+                ? from + results.length < total
+                : results.length >= size,
+        },
+    });
+}
+/**
+ * Searches for people by name or email.
+ */
+export async function searchPeople(query, limit = 10) {
+    const tokenResult = requireSubstrateToken();
+    if (!tokenResult.ok) {
+        return tokenResult;
+    }
+    const token = tokenResult.value;
+    const cvid = crypto.randomUUID();
+    const logicalId = crypto.randomUUID();
+    const body = {
+        EntityRequests: [{
+                Query: {
+                    QueryString: query,
+                    DisplayQueryString: query,
+                },
+                EntityType: 'People',
+                Size: limit,
+                Fields: [
+                    'Id',
+                    'MRI',
+                    'DisplayName',
+                    'EmailAddresses',
+                    'GivenName',
+                    'Surname',
+                    'JobTitle',
+                    'Department',
+                    'CompanyName',
+                ],
+            }],
+        cvid,
+        logicalId,
+    };
+    const response = await httpRequest(SUBSTRATE_API.peopleSearch, {
+        method: 'POST',
+        headers: getBearerHeaders(token),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        if (response.error.code === ErrorCode.AUTH_EXPIRED) {
+            clearTokenCache();
+        }
+        return response;
+    }
+    const results = parsePeopleResults(response.value.data.Groups);
+    return ok({
+        results,
+        returned: results.length,
+    });
+}
+/**
+ * Gets the user's frequently contacted people.
+ */
+export async function getFrequentContacts(limit = 50) {
+    const tokenResult = requireSubstrateToken();
+    if (!tokenResult.ok) {
+        return tokenResult;
+    }
+    const token = tokenResult.value;
+    const cvid = crypto.randomUUID();
+    const logicalId = crypto.randomUUID();
+    const body = {
+        EntityRequests: [{
+                Query: {
+                    QueryString: '',
+                    DisplayQueryString: '',
+                },
+                EntityType: 'People',
+                Size: limit,
+                Fields: [
+                    'Id',
+                    'MRI',
+                    'DisplayName',
+                    'EmailAddresses',
+                    'GivenName',
+                    'Surname',
+                    'JobTitle',
+                    'Department',
+                    'CompanyName',
+                ],
+            }],
+        cvid,
+        logicalId,
+    };
+    const response = await httpRequest(SUBSTRATE_API.frequentContacts, {
+        method: 'POST',
+        headers: getBearerHeaders(token),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        if (response.error.code === ErrorCode.AUTH_EXPIRED) {
+            clearTokenCache();
+        }
+        return response;
+    }
+    const contacts = parsePeopleResults(response.value.data.Groups);
+    return ok({
+        results: contacts,
+        returned: contacts.length,
+    });
+}
+/**
+ * Searches for Teams channels by name using both:
+ * 1. User's own teams/channels (Teams List API) - reliable, shows membership
+ * 2. Organisation-wide discovery (Substrate suggestions) - broader but less reliable
+ *
+ * Results are merged and deduplicated, with membership status indicated.
+ *
+ * @param query - Channel name to search for
+ * @param limit - Maximum number of results (default: 10, max: 50)
+ */
+export async function searchChannels(query, limit = 10) {
+    const tokenResult = requireSubstrateToken();
+    if (!tokenResult.ok) {
+        return tokenResult;
+    }
+    const token = tokenResult.value;
+    // Run both searches in parallel
+    const [orgSearchResult, myTeamsResult] = await Promise.all([
+        searchChannelsOrgWide(query, limit, token),
+        getMyTeamsAndChannels(),
+    ]);
+    // Build a map of channel IDs the user is a member of
+    const memberChannelIds = new Set();
+    const myChannelsMatching = [];
+    if (myTeamsResult.ok) {
+        // Filter the user's channels by the query and collect matching ones
+        const matching = filterChannelsByName(myTeamsResult.value.teams, query);
+        for (const channel of matching) {
+            memberChannelIds.add(channel.channelId);
+            myChannelsMatching.push(channel);
+        }
+        // Also add all channel IDs to the set for membership lookup
+        for (const team of myTeamsResult.value.teams) {
+            for (const channel of team.channels) {
+                memberChannelIds.add(channel.channelId);
+            }
+        }
+    }
+    // Process org-wide results, marking membership status
+    const orgChannels = [];
+    if (orgSearchResult.ok) {
+        for (const channel of orgSearchResult.value) {
+            // Mark whether user is a member
+            channel.isMember = memberChannelIds.has(channel.channelId);
+            orgChannels.push(channel);
+        }
+    }
+    // Merge results: start with user's matching channels (definitely accessible),
+    // then add org-wide results that aren't duplicates
+    const seenIds = new Set();
+    const merged = [];
+    // First add channels from user's teams (reliable, known accessible)
+    for (const channel of myChannelsMatching) {
+        if (!seenIds.has(channel.channelId)) {
+            seenIds.add(channel.channelId);
+            merged.push(channel);
+        }
+    }
+    // Then add org-wide results that aren't duplicates
+    for (const channel of orgChannels) {
+        if (!seenIds.has(channel.channelId)) {
+            seenIds.add(channel.channelId);
+            merged.push(channel);
+        }
+    }
+    // Apply limit
+    const limited = merged.slice(0, limit);
+    return ok({
+        results: limited,
+        returned: limited.length,
+    });
+}
+/**
+ * Internal: Searches for channels org-wide using the Substrate suggestions API.
+ *
+ * This is a typeahead/autocomplete API, so matching behaviour may be inconsistent
+ * for multi-word queries. Used as a supplement to the user's own teams list.
+ */
+async function searchChannelsOrgWide(query, limit, token) {
+    const cvid = crypto.randomUUID();
+    const logicalId = crypto.randomUUID();
+    const body = {
+        EntityRequests: [{
+                Query: {
+                    QueryString: query,
+                    DisplayQueryString: query,
+                },
+                EntityType: 'TeamsChannel',
+                Size: Math.min(limit, 50),
+            }],
+        cvid,
+        logicalId,
+    };
+    const response = await httpRequest(SUBSTRATE_API.channelSearch, {
+        method: 'POST',
+        headers: getBearerHeaders(token),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        if (response.error.code === ErrorCode.AUTH_EXPIRED) {
+            clearTokenCache();
+        }
+        return response;
+    }
+    const data = response.value.data;
+    const results = parseChannelResults(data?.Groups);
+    // Mark all org-wide results as isMember: false initially
+    // (caller will update based on actual membership)
+    for (const result of results) {
+        result.isMember = false;
+    }
+    return ok(results);
+}

package/dist/auth/crypto.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Encryption utilities for credential storage.
+ *
+ * Uses machine-specific key derivation to encrypt sensitive data at rest.
+ * This is not foolproof security, but significantly raises the bar compared
+ * to plaintext storage.
+ */
+/** Encrypted data format. */
+export interface EncryptedData {
+    /** Initialisation vector (hex). */
+    iv: string;
+    /** Encrypted content (hex). */
+    content: string;
+    /** Authentication tag (hex). */
+    tag: string;
+    /** Version marker for future upgrades. */
+    version: number;
+}
+/**
+ * Encrypts a string value.
+ */
+export declare function encrypt(plaintext: string): EncryptedData;
+/**
+ * Decrypts encrypted data.
+ *
+ * @throws Error if decryption fails (wrong machine, corrupted data, etc.)
+ */
+export declare function decrypt(data: EncryptedData): string;
+/**
+ * Checks if data looks like encrypted format.
+ */
+export declare function isEncrypted(data: unknown): data is EncryptedData;

package/dist/auth/crypto.js

@@ -0,0 +1,66 @@
+/**
+ * Encryption utilities for credential storage.
+ *
+ * Uses machine-specific key derivation to encrypt sensitive data at rest.
+ * This is not foolproof security, but significantly raises the bar compared
+ * to plaintext storage.
+ */
+import * as crypto from 'crypto';
+import * as os from 'os';
+/** Algorithm for encryption. */
+const ALGORITHM = 'aes-256-gcm';
+/** Salt for key derivation. */
+const SALT = 'teams-mcp-credential-salt-v1';
+/** Derives an encryption key from machine-specific values. */
+function deriveKey() {
+    // Combine hostname and username for machine-specific key
+    const machineId = `${os.hostname()}:${os.userInfo().username}`;
+    return crypto.scryptSync(machineId, SALT, 32);
+}
+/**
+ * Encrypts a string value.
+ */
+export function encrypt(plaintext) {
+    const key = deriveKey();
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+    let encrypted = cipher.update(plaintext, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    const tag = cipher.getAuthTag();
+    return {
+        iv: iv.toString('hex'),
+        content: encrypted,
+        tag: tag.toString('hex'),
+        version: 1,
+    };
+}
+/**
+ * Decrypts encrypted data.
+ *
+ * @throws Error if decryption fails (wrong machine, corrupted data, etc.)
+ */
+export function decrypt(data) {
+    if (data.version !== 1) {
+        throw new Error(`Unsupported encryption version: ${data.version}`);
+    }
+    const key = deriveKey();
+    const iv = Buffer.from(data.iv, 'hex');
+    const tag = Buffer.from(data.tag, 'hex');
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(tag);
+    let decrypted = decipher.update(data.content, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted;
+}
+/**
+ * Checks if data looks like encrypted format.
+ */
+export function isEncrypted(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    return (typeof obj.iv === 'string' &&
+        typeof obj.content === 'string' &&
+        typeof obj.tag === 'string' &&
+        typeof obj.version === 'number');
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Auth module exports.
+ */
+export * from './session-store.js';
+export * from './token-extractor.js';
+export { encrypt, decrypt, isEncrypted, type EncryptedData } from './crypto.js';

package/dist/auth/index.js

@@ -0,0 +1,6 @@
+/**
+ * Auth module exports.
+ */
+export * from './session-store.js';
+export * from './token-extractor.js';
+export { encrypt, decrypt, isEncrypted } from './crypto.js';