Copilot Studio Agent Direct Line MCP Server

Instructions

Implementation Reference

• src/server/mcp-server.ts:224-339 (handler)

  The core handler function that executes the send_message tool logic: validates input using SendMessageArgsSchema, manages or creates conversations, sends the message via DirectLineClient, polls for the bot's response, logs audit, and returns conversationId, response, and activityId.

  private async handleSendMessage(args: Record<string, unknown>, userContext?: UserContext) {
    const { message, conversationId } = validateToolArgs(SendMessageArgsSchema, args);
  
    // Validate permissions if user context exists
    if (userContext && conversationId) {
      this.validateUserConversationAccess(userContext.userId, conversationId);
    }
  
    try {
      let convId = conversationId;
      let convState;
  
      // Get or create conversation
      if (convId) {
        convState = this.conversationManager.getConversation(convId);
        if (!convState) {
          throw new Error(`Conversation ${convId} not found or expired`);
        }
      } else {
        // Create new conversation with user-specific client ID
        const clientId = userContext
          ? `user-${userContext.userId}-${Date.now()}`
          : `mcp-client-${Date.now()}`;
        convState = await this.conversationManager.createConversation(clientId);
        convId = convState.conversationId;
  
        // Associate conversation with user
        if (userContext) {
          this.associateConversationWithUser(userContext.userId, convId);
        }
      }
  
      // Send message to Direct Line with user metadata
      const activityId = await this.client.sendActivity(
        {
          conversationId: convId,
          activity: {
            type: 'message',
            from: {
              id: convState.clientId,
              name: userContext?.name || 'MCP User',
            },
            text: message,
            timestamp: new Date().toISOString(),
            // Add user metadata to activity
            channelData: userContext
              ? {
                  userId: userContext.userId,
                  userEmail: userContext.email,
                  tenantId: userContext.tenantId,
                }
              : undefined,
          },
        },
        convState.token
      );
  
      // Poll for response
      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: convId,
            watermark: convState.watermark,
          },
          convState.token
        );
  
        if (activitySet.watermark) {
          this.conversationManager.updateWatermark(convId, activitySet.watermark);
        }
  
        const botActivities = activitySet.activities.filter(
          (a) => a.type === 'message' && a.from?.id !== convState.clientId
        );
  
        if (botActivities.length > 0) {
          botActivities.forEach((activity) => {
            this.conversationManager.addToHistory(convId!, activity);
          });
  
          const latestBot = botActivities[botActivities.length - 1];
          botResponse = latestBot.text || '[No text response]';
          break;
        }
      }
  
      if (!botResponse) {
        botResponse = '[No response received within timeout period]';
      }
  
      // Audit log
      this.logAudit({
        timestamp: Date.now(),
        userId: userContext?.userId,
        action: 'send_message',
        conversationId: convId,
        details: { activityId },
      });
  
      return createSuccessResponse({
        conversationId: convId,
        response: botResponse,
        activityId,
      });
    } catch (error) {
      throw new Error(
        `Failed to send message: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/server/tool-schemas.ts:8-15 (schema)

  Zod schema for validating send_message tool arguments: requires 'message' string (non-empty), optional 'conversationId' string. Used in handleSendMessage via validateToolArgs.

   * Schema for send_message tool arguments
   */
  export const SendMessageArgsSchema = z.object({
    message: z.string().min(1, 'Message cannot be empty'),
    conversationId: z.string().optional(),
  });
  
  export type SendMessageArgs = z.infer<typeof SendMessageArgsSchema>;

• src/server/mcp-server.ts:116-133 (registration)

  Tool registration in the MCP server's ListToolsRequestSchema handler, defining name, description, and inputSchema for send_message.

  {
    name: 'send_message',
    description: 'Send a message to the Copilot Studio Agent',
    inputSchema: {
      type: 'object',
      properties: {
        message: {
          type: 'string',
          description: 'The message text to send',
        },
        conversationId: {
          type: 'string',
          description: 'Optional conversation ID to continue existing conversation',
        },
      },
      required: ['message'],
    },
  },

• src/server/mcp-server.ts:194-196 (registration)

  Dispatch/registration in CallToolRequestSchema handler: routes 'send_message' calls to handleSendMessage function.

  switch (name) {
    case 'send_message':
      return await this.handleSendMessage(args || {}, userContext);

• src/server/mcp-server.ts:689-704 (registration)

  Duplicate tool registration for HTTP transport mode in handleHttpMessage 'tools/list' case.

  name: 'send_message',
  description: 'Send a message to the Copilot Studio Agent',
  inputSchema: {
    type: 'object',
    properties: {
      message: {
        type: 'string',
        description: 'The message text to send',
      },
      conversationId: {
        type: 'string',
        description: 'Optional conversation ID to continue existing conversation',
      },
    },
    required: ['message'],
  },