Copilot Studio Agent Direct Line MCP Server

Instructions

Implementation Reference

• src/server/mcp-server.ts:450-492 (handler)

  Main handler for end_conversation tool: validates input, authorizes user, retrieves conversation state, delegates to conversationManager.endConversation, cleans user mapping, audits, and returns success response.

   * Handle end_conversation tool with user context
   */
  private async handleEndConversation(args: Record<string, unknown>, userContext?: UserContext) {
    const { conversationId } = validateToolArgs(EndConversationArgsSchema, args);
  
    // Validate permissions if user context exists
    if (userContext) {
      this.validateUserConversationAccess(userContext.userId, conversationId);
    }
  
    try {
      const convState = this.conversationManager.getConversation(conversationId);
      if (!convState) {
        throw new Error(`Conversation ${conversationId} not found or already ended`);
      }
  
      // End the conversation
      this.conversationManager.endConversation(conversationId);
  
      // Remove from user mapping
      if (userContext) {
        this.removeUserConversation(userContext.userId, conversationId);
      }
  
      // Audit log
      this.logAudit({
        timestamp: Date.now(),
        userId: userContext?.userId,
        action: 'end_conversation',
        conversationId,
        details: { messageCount: convState.messageHistory.length },
      });
  
      return createSuccessResponse({
        conversationId,
        status: 'ended',
        messageCount: convState.messageHistory.length,
      });
    } catch (error) {
      throw new Error(
        `Failed to end conversation: ${error instanceof Error ? error.message : String(error)}`
      );
    }

• src/server/tool-schemas.ts:27-33 (schema)

  Zod schema for validating end_conversation tool arguments, requiring a conversationId string.

   * Schema for end_conversation tool arguments
   */
  export const EndConversationArgsSchema = z.object({
    conversationId: z.string().min(1, 'Conversation ID is required'),
  });
  
  export type EndConversationArgs = z.infer<typeof EndConversationArgsSchema>;

• src/server/mcp-server.ts:147-160 (registration)

  Tool registration in listTools handler: defines name, description, and inputSchema for end_conversation.

  {
    name: 'end_conversation',
    description: 'End an existing conversation and clean up resources',
    inputSchema: {
      type: 'object',
      properties: {
        conversationId: {
          type: 'string',
          description: 'Conversation ID to terminate',
        },
      },
      required: ['conversationId'],
    },
  },

• src/services/conversation-manager.ts:155-181 (helper)

  Helper method implementing conversation cleanup: updates metrics, clears timers, removes state from map, and logs.

  endConversation(conversationId: string): void {
    const state = this.conversations.get(conversationId);
    if (!state) return;
  
    const lifetime = Date.now() - state.createdAt;
  
    // Update metrics
    this.metrics.cleanedUp++;
    this.metrics.activeCount = this.conversations.size - 1;
    this.metrics.averageLifetime =
      (this.metrics.averageLifetime * (this.metrics.cleanedUp - 1) + lifetime) /
      this.metrics.cleanedUp;
  
    // Clear timeout
    const timer = this.timeoutTimers.get(conversationId);
    if (timer) {
      clearTimeout(timer);
      this.timeoutTimers.delete(conversationId);
    }
  
    // Remove conversation
    this.conversations.delete(conversationId);
  
    console.error(
      `[ConversationManager] Ended conversation ${conversationId} (lifetime: ${(lifetime / 1000).toFixed(0)}s)`
    );
  }