search_messages
Search across Microsoft Teams channels and chats using advanced KQL filters for sender, mentions, attachments, and more. Retrieve relevant messages with customizable scope and result limits.
Instructions
Search for messages across all Microsoft Teams channels and chats using Microsoft Search API. Supports advanced KQL syntax for filtering by sender, mentions, attachments, and more.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| enableTopResults | No | Enable relevance-based ranking | |
| limit | No | Number of results to return | |
| query | Yes | Search query. Supports KQL syntax like 'from:user mentions:userId hasAttachment:true' | |
| scope | No | Scope of search | all |
Implementation Reference
- src/tools/search.ts:35-117 (handler)Handler function that performs Microsoft Graph Search API query for chatMessages, applies scope filters, processes hits into results, and returns JSON-formatted response.async ({ query, scope, limit, enableTopResults }) => { try { const client = await graphService.getClient(); // Build the search request const searchRequest: SearchRequest = { entityTypes: ["chatMessage"], query: { queryString: query, }, from: 0, size: limit, enableTopResults, }; // Add scope-specific filters to the query if needed let enhancedQuery = query; if (scope === "channels") { enhancedQuery = `${query} AND (channelIdentity/channelId:*)`; } else if (scope === "chats") { enhancedQuery = `${query} AND (chatId:* AND NOT channelIdentity/channelId:*)`; } searchRequest.query.queryString = enhancedQuery; const response = (await client .api("/search/query") .post({ requests: [searchRequest] })) as SearchResponse; if (!response?.value?.length || !response.value[0]?.hitsContainers?.length) { return { content: [ { type: "text", text: "No messages found matching your search criteria.", }, ], }; } const hits = response.value[0].hitsContainers[0].hits; const searchResults = hits.map((hit: SearchHit) => ({ id: hit.resource.id, summary: hit.summary, rank: hit.rank, content: hit.resource.body?.content || "No content", from: hit.resource.from?.user?.displayName || "Unknown", createdDateTime: hit.resource.createdDateTime, chatId: hit.resource.chatId, teamId: hit.resource.channelIdentity?.teamId, channelId: hit.resource.channelIdentity?.channelId, })); return { content: [ { type: "text", text: JSON.stringify( { query, scope, totalResults: response.value[0].hitsContainers[0].total, results: searchResults, moreResultsAvailable: response.value[0].hitsContainers[0].moreResultsAvailable, }, null, 2 ), }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `❌ Error searching messages: ${errorMessage}`, }, ], }; } }
- src/tools/search.ts:11-34 (schema)Zod input schema defining parameters for search_messages tool: query (string), scope (enum), limit (number 1-100), enableTopResults (boolean).{ query: z .string() .describe( "Search query. Supports KQL syntax like 'from:user mentions:userId hasAttachment:true'" ), scope: z .enum(["all", "channels", "chats"]) .optional() .default("all") .describe("Scope of search"), limit: z .number() .min(1) .max(100) .optional() .default(25) .describe("Number of results to return"), enableTopResults: z .boolean() .optional() .default(true) .describe("Enable relevance-based ranking"), },
- src/tools/search.ts:8-118 (registration)Registration of the search_messages tool on the MCP server, specifying name, description, input schema, and handler function.server.tool( "search_messages", "Search for messages across all Microsoft Teams channels and chats using Microsoft Search API. Supports advanced KQL syntax for filtering by sender, mentions, attachments, and more.", { query: z .string() .describe( "Search query. Supports KQL syntax like 'from:user mentions:userId hasAttachment:true'" ), scope: z .enum(["all", "channels", "chats"]) .optional() .default("all") .describe("Scope of search"), limit: z .number() .min(1) .max(100) .optional() .default(25) .describe("Number of results to return"), enableTopResults: z .boolean() .optional() .default(true) .describe("Enable relevance-based ranking"), }, async ({ query, scope, limit, enableTopResults }) => { try { const client = await graphService.getClient(); // Build the search request const searchRequest: SearchRequest = { entityTypes: ["chatMessage"], query: { queryString: query, }, from: 0, size: limit, enableTopResults, }; // Add scope-specific filters to the query if needed let enhancedQuery = query; if (scope === "channels") { enhancedQuery = `${query} AND (channelIdentity/channelId:*)`; } else if (scope === "chats") { enhancedQuery = `${query} AND (chatId:* AND NOT channelIdentity/channelId:*)`; } searchRequest.query.queryString = enhancedQuery; const response = (await client .api("/search/query") .post({ requests: [searchRequest] })) as SearchResponse; if (!response?.value?.length || !response.value[0]?.hitsContainers?.length) { return { content: [ { type: "text", text: "No messages found matching your search criteria.", }, ], }; } const hits = response.value[0].hitsContainers[0].hits; const searchResults = hits.map((hit: SearchHit) => ({ id: hit.resource.id, summary: hit.summary, rank: hit.rank, content: hit.resource.body?.content || "No content", from: hit.resource.from?.user?.displayName || "Unknown", createdDateTime: hit.resource.createdDateTime, chatId: hit.resource.chatId, teamId: hit.resource.channelIdentity?.teamId, channelId: hit.resource.channelIdentity?.channelId, })); return { content: [ { type: "text", text: JSON.stringify( { query, scope, totalResults: response.value[0].hitsContainers[0].total, results: searchResults, moreResultsAvailable: response.value[0].hitsContainers[0].moreResultsAvailable, }, null, 2 ), }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `❌ Error searching messages: ${errorMessage}`, }, ], }; } } );
- src/index.ts:136-136 (registration)Top-level call to registerSearchTools function, which registers the search_messages tool among others, in the main MCP server setup.registerSearchTools(server, graphService);