Canvas MCP Server

Instructions

    List conversations for the current user.

    Args:
        scope: Conversation scope ("unread", "starred", "sent", "archived", or "all")
        filter_ids: Optional list of conversation IDs to filter by
        filter_mode: How to apply filter_ids ("and" or "or")
        include_participants: Include participant information
        include_all_ids: Include all conversation participant IDs

    Returns:
        List of conversations
    

Implementation Reference

• src/canvas_mcp/tools/messaging.py:178-228 (handler)

  The core handler function for the 'list_conversations' tool. It validates input parameters, constructs API parameters, calls the Canvas conversations API endpoint, and returns formatted results or errors.

  @mcp.tool()
  async def list_conversations(
      scope: str = "unread",
      filter_ids: list[str] | None = None,
      filter_mode: str = "and",
      include_participants: bool = True,
      include_all_ids: bool = False
  ) -> dict[str, Any]:
      """
      List conversations for the current user.
  
      Args:
          scope: Conversation scope ("unread", "starred", "sent", "archived", or "all")
          filter_ids: Optional list of conversation IDs to filter by
          filter_mode: How to apply filter_ids ("and" or "or")
          include_participants: Include participant information
          include_all_ids: Include all conversation participant IDs
  
      Returns:
          List of conversations
      """
  
      valid_scopes = ["unread", "starred", "sent", "archived", "all"]
      if scope not in valid_scopes:
          return {"error": f"scope must be one of: {', '.join(valid_scopes)}"}
  
      try:
          params = {
              "scope": scope,
              "include_participants": include_participants,
              "include_all_conversation_ids": include_all_ids
          }
  
          if filter_ids:
              params["filter[]"] = filter_ids
              params["filter_mode"] = filter_mode
  
          response = await make_canvas_request("get", "/conversations", params=params)
  
          if "error" in response:
              return response
  
          return {
              "success": True,
              "conversations": response,
              "count": len(response) if isinstance(response, list) else 0
          }
  
      except Exception as e:
          print(f"Error listing conversations: {str(e)}", file=sys.stderr)
          return {"error": f"Failed to list conversations: {str(e)}"}

• src/canvas_mcp/server.py:54-54 (registration)

  The registration call within register_all_tools that invokes register_messaging_tools(mcp), which defines and registers the list_conversations tool via @mcp.tool() decorator.

  register_messaging_tools(mcp)

• src/canvas_mcp/tools/messaging.py:11-11 (registration)

  The registration function that contains the @mcp.tool() decorator and definition for list_conversations.

  def register_messaging_tools(mcp: FastMCP) -> None:

• src/canvas_mcp/tools/messaging.py:179-197 (schema)

  Parameter type hints and docstring defining the tool schema for input validation and documentation.

  async def list_conversations(
      scope: str = "unread",
      filter_ids: list[str] | None = None,
      filter_mode: str = "and",
      include_participants: bool = True,
      include_all_ids: bool = False
  ) -> dict[str, Any]:
      """
      List conversations for the current user.
  
      Args:
          scope: Conversation scope ("unread", "starred", "sent", "archived", or "all")
          filter_ids: Optional list of conversation IDs to filter by
          filter_mode: How to apply filter_ids ("and" or "or")
          include_participants: Include participant information
          include_all_ids: Include all conversation participant IDs
  
      Returns:
          List of conversations