Copilot Studio Agent Direct Line MCP Server

Instructions

Implementation Reference

• src/server/mcp-server.ts:342-447 (handler)

  Main execution logic for the 'start_conversation' MCP tool: validates args, creates conversation via ConversationManager, optionally sends initial message and polls for bot response, handles user context and auditing.
  * Handle start_conversation tool with user context */ private async handleStartConversation( args: Record<string, unknown>, userContext?: UserContext ) { const { initialMessage } = validateToolArgs(StartConversationArgsSchema, args); try { // Create new conversation with user-specific client ID const clientId = userContext ? `user-${userContext.userId}-${Date.now()}` : `mcp-client-${Date.now()}`; const convState = await this.conversationManager.createConversation(clientId); // Associate conversation with user if (userContext) { this.associateConversationWithUser(userContext.userId, convState.conversationId); } let result: { conversationId: string; status: string; response?: string; activityId?: string; } = { conversationId: convState.conversationId, status: 'started', }; // If initial message provided, send it if (initialMessage && typeof initialMessage === 'string') { const activityId = await this.client.sendActivity( { conversationId: convState.conversationId, activity: { type: 'message', from: { id: clientId, name: userContext?.name || 'MCP User' }, text: initialMessage, timestamp: new Date().toISOString(), channelData: userContext ? { userId: userContext.userId, userEmail: userContext.email, tenantId: userContext.tenantId, } : undefined, }, }, convState.token ); // Poll for response (same logic as send_message) const startTime = Date.now(); const timeout = 30000; let botResponse = ''; while (Date.now() - startTime < timeout) { await new Promise((resolve) => setTimeout(resolve, 1000)); const activitySet = await this.client.getActivities( { conversationId: convState.conversationId, watermark: convState.watermark, }, convState.token ); if (activitySet.watermark) { this.conversationManager.updateWatermark(convState.conversationId, activitySet.watermark); } const botActivities = activitySet.activities.filter( (a) => a.type === 'message' && a.from?.id !== clientId ); if (botActivities.length > 0) { botActivities.forEach((activity) => { this.conversationManager.addToHistory(convState.conversationId, activity); }); const latestBot = botActivities[botActivities.length - 1]; botResponse = latestBot.text || '[No text response]'; break; } } result.response = botResponse || '[No response received within timeout period]'; result.activityId = activityId; } // Audit log this.logAudit({ timestamp: Date.now(), userId: userContext?.userId, action: 'start_conversation', conversationId: convState.conversationId, }); return createSuccessResponse(result); } catch (error) { throw new Error( `Failed to start conversation: ${error instanceof Error ? error.message : String(error)}` ); } }
• src/server/tool-schemas.ts:18-24 (schema)

  Zod schema definition for 'start_conversation' tool input arguments (initialMessage optional string). Used for validation in the handler.
  * Schema for start_conversation tool arguments */ export const StartConversationArgsSchema = z.object({ initialMessage: z.string().min(1, 'Initial message cannot be empty').optional(), }); export type StartConversationArgs = z.infer<typeof StartConversationArgsSchema>;
• src/server/mcp-server.ts:135-146 (registration)

  Registration of 'start_conversation' tool in the MCP listTools handler, including name, description, and JSON input schema.
  name: 'start_conversation', description: 'Start a new conversation with the Copilot Studio Agent', inputSchema: { type: 'object', properties: { initialMessage: { type: 'string', description: 'Optional first message to send', }, }, }, },
• src/server/mcp-server.ts:707-718 (registration)

  Duplicate registration of 'start_conversation' tool in the HTTP transport tools/list handler.
  name: 'start_conversation', description: 'Start a new conversation with the Copilot Studio Agent', inputSchema: { type: 'object', properties: { initialMessage: { type: 'string', description: 'Optional first message to send', }, }, }, },
• src/server/mcp-server.ts:197-198 (handler)

  Dispatcher case in stdio CallToolRequestSchema handler that routes to the main start_conversation handler.
  case 'start_conversation': return await this.handleStartConversation(args || {}, userContext);