Copilot Studio Agent Direct Line MCP Server

Instructions

Implementation Reference

• src/server/mcp-server.ts:498-550 (handler)

  The primary handler function for the 'get_conversation_history' tool. Validates input using the schema, checks user permissions, retrieves conversation state from the manager, slices history if limit provided, formats messages, logs audit, and returns structured response.

  private async handleGetConversationHistory(
    args: Record<string, unknown>,
    userContext?: UserContext
  ) {
    const { conversationId, limit } = validateToolArgs(GetConversationHistoryArgsSchema, 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 expired`);
      }
  
      let history = convState.messageHistory;
  
      if (limit && limit > 0) {
        history = history.slice(-limit);
      }
  
      const formattedHistory = history.map((activity) => ({
        id: activity.id,
        type: activity.type,
        timestamp: activity.timestamp,
        from: activity.from,
        text: activity.text,
        attachments: activity.attachments,
      }));
  
      // Audit log
      this.logAudit({
        timestamp: Date.now(),
        userId: userContext?.userId,
        action: 'get_conversation_history',
        conversationId,
        details: { messageCount: formattedHistory.length },
      });
  
      return createSuccessResponse({
        conversationId,
        messageCount: formattedHistory.length,
        totalMessages: convState.messageHistory.length,
        messages: formattedHistory,
      });
    } catch (error) {
      throw new Error(
        `Failed to get conversation history: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/server/tool-schemas.ts:35-43 (schema)

  Zod schema defining input arguments for the tool: required conversationId string and optional positive integer limit. Used for validation in the handler.

  /**
   * Schema for get_conversation_history tool arguments
   */
  export const GetConversationHistoryArgsSchema = z.object({
    conversationId: z.string().min(1, 'Conversation ID is required'),
    limit: z.number().int().positive().optional(),
  });
  
  export type GetConversationHistoryArgs = z.infer<typeof GetConversationHistoryArgsSchema>;

• src/server/mcp-server.ts:161-178 (registration)

  Tool registration in the ListToolsRequestSchema handler for stdio transport, providing name, description, and JSON input schema.

  {
    name: 'get_conversation_history',
    description: 'Retrieve message history for a conversation',
    inputSchema: {
      type: 'object',
      properties: {
        conversationId: {
          type: 'string',
          description: 'Conversation ID',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of messages to return',
        },
      },
      required: ['conversationId'],
    },
  },

• src/server/mcp-server.ts:733-750 (registration)

  Tool registration in the HTTP 'tools/list' handler, providing name, description, and JSON input schema.

  {
    name: 'get_conversation_history',
    description: 'Retrieve message history for a conversation',
    inputSchema: {
      type: 'object',
      properties: {
        conversationId: {
          type: 'string',
          description: 'Conversation ID',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of messages to return',
        },
      },
      required: ['conversationId'],
    },
  },