Skip to content

A platform for community discussion. Free, open, simple.

17.7 KB
Raw Blame
# frozen_string_literal: true

module DiscourseMcp
  module Tools
    class ReadTopicPosts
      REQUIRED_SCOPES = [Scopes::CONTENT_READ].freeze
      SELECTION_KEYS = {
        "latest" => %w[limit replies_only],
        "earliest" => %w[limit replies_only],
        "post_ids" => %w[post_ids],
        "around_post" => %w[post_number limit],
        "usernames" => %w[usernames limit replies_only],
      }.freeze
      OUTPUT_SCHEMA =
        OutputSchema.object(
          topic_id: OutputSchema::INTEGER,
          selection_mode: OutputSchema::STRING,
          posts: OutputSchema::OBJECT_ARRAY,
          meta: OutputSchema::OBJECT,
        )

      def self.call(arguments:, request_context:)
        validate_selection!(arguments)
        topic = Topic.with_deleted.find_by(id: arguments.fetch("topic_id"))
        guardian = request_context.guardian
        if topic.blank? || !guardian.can_see?(topic)
          raise DiscourseMcp::ToolError, I18n.t("mcp.errors.topic_not_found")
        end
        ToolHelpers.ensure_private_message_scope!(topic, request_context, access: :read)

        selection_mode = arguments.fetch("selection_mode")
        limit = arguments.fetch("limit", 20)
        stream_size = nil
        selected_ids = nil
        posts = nil

        if selection_mode == "post_ids"
          selected_ids = arguments.fetch("post_ids")
        elsif selection_mode == "around_post"
          posts = around_posts(topic, arguments.fetch("post_number"), limit, request_context.user)
        else
          stream_size, selected_ids = stream_selection(topic, arguments, request_context)
        end

        posts ||= posts_for_ids(topic, selected_ids, request_context.user, guardian)
        ToolHelpers.text_and_structured(
          topic_id: topic.id,
          selection_mode:,
          posts: posts.map { |post| ToolHelpers.evidence_post_json(post, include_raw: true) },
          meta: {
            visible_stream_size: stream_size,
            selected: selected_ids&.length || posts.length,
            returned: posts.length,
            max_requests: %w[post_ids around_post].include?(selection_mode) ? 1 : 2,
            exhaustive: false,
          },
        )
      end

      def self.validate_selection!(arguments)
        selection_mode = arguments["selection_mode"]
        allowed_keys = SELECTION_KEYS[selection_mode]
        supplied_keys = arguments.filter_map { |key, value| key unless value.nil? }
        supplied_selection_keys = supplied_keys - %w[topic_id selection_mode]
        required_key = "post_ids" if selection_mode == "post_ids"
        required_key = "post_number" if selection_mode == "around_post"
        required_key = "usernames" if selection_mode == "usernames"

        if allowed_keys.blank? ||
             supplied_selection_keys.any? { |key| allowed_keys.exclude?(key) } ||
             (required_key && arguments[required_key].blank?)
          raise DiscourseMcp::ToolError, I18n.t("mcp.errors.invalid_post_selection")
        end
      end
      private_class_method :validate_selection!

      def self.stream_selection(topic, arguments, request_context)
        options = { limit: 1, include_suggested: false, include_related: false }
        if arguments.fetch("selection_mode") == "usernames"
          options[:username_filters] = arguments.fetch("usernames")
        end
        topic_view = TopicView.new(topic, request_context.user, options)
        posts =
          request_context.guardian.filter_hidden_posts(
            topic_view.filtered_posts,
            category: topic.category,
          )
        stream_size = posts.count
        posts = posts.where("posts.post_number > 1") if arguments["replies_only"]
        limit = arguments.fetch("limit", 20)
        selected_ids =
          if arguments.fetch("selection_mode") == "latest"
            posts.reorder(sort_order: :desc).limit(limit).pluck(:id).reverse
          else
            posts.reorder(sort_order: :asc).limit(limit).pluck(:id)
          end
        [stream_size, selected_ids]
      end
      private_class_method :stream_selection

      def self.around_posts(topic, post_number, limit, user)
        topic_view =
          TopicView.new(
            topic,
            user,
            post_number:,
            limit:,
            include_suggested: false,
            include_related: false,
          )
        guardian = topic_view.guardian
        posts_visible_to_guardian(topic_view.posts, topic, guardian).first(limit)
      end
      private_class_method :around_posts

      def self.posts_for_ids(topic, post_ids, user, guardian)
        topic_view =
          TopicView.new(
            topic,
            user,
            post_ids:,
            limit: 50,
            include_suggested: false,
            include_related: false,
          )
        visible_posts = posts_visible_to_guardian(topic_view.posts, topic, guardian)
        posts = visible_posts.index_by(&:id)
        post_ids.filter_map { |post_id| posts[post_id] }
      end
      private_class_method :posts_for_ids

      def self.posts_visible_to_guardian(posts, topic, guardian)
        posts.select do |post|
          post.association(:topic).target = topic
          guardian.can_see?(post)
        end
      end
      private_class_method :posts_visible_to_guardian
    end

    class GetPostReplies
      REQUIRED_SCOPES = [Scopes::CONTENT_READ].freeze
      DIRECT_REPLIES_LIMIT = 20
      MODES = %w[reply_ids direct_replies reply_history].freeze
      OUTPUT_SCHEMA =
        OutputSchema.object(
          optional: %w[posts replies],
          post_id: OutputSchema::INTEGER,
          mode: OutputSchema::STRING,
          posts: OutputSchema::OBJECT_ARRAY,
          replies: OutputSchema::OBJECT_ARRAY,
          meta: OutputSchema::OBJECT,
        )

      def self.call(arguments:, request_context:)
        guardian = request_context.guardian
        post = ToolHelpers.visible_post!(arguments.fetch("post_id"), request_context)
        mode = arguments.fetch("mode", "reply_ids")
        if MODES.exclude?(mode)
          raise DiscourseMcp::ToolError, I18n.t("mcp.errors.invalid_reply_mode")
        end

        return reply_ids_result(post, guardian) if mode == "reply_ids"

        posts =
          if mode == "direct_replies"
            direct_replies(post, arguments["after_post_number"], request_context)
          else
            reply_history(post, request_context)
          end

        ToolHelpers.text_and_structured(
          post_id: post.id,
          mode:,
          posts: posts.map { |reply| ToolHelpers.evidence_post_json(reply, include_raw: true) },
          meta: {
            returned: posts.length,
            has_more: nil,
            page_was_full: mode == "direct_replies" ? posts.length == DIRECT_REPLIES_LIMIT : nil,
            upstream_limit:
              mode == "direct_replies" ? DIRECT_REPLIES_LIMIT : "site max_reply_history",
          },
        )
      end

      def self.reply_ids_result(post, guardian)
        replies = post.reply_ids(guardian)
        reply_posts = Post.with_deleted.where(id: replies.pluck(:id)).index_by(&:id)
        visible_replies =
          replies.select do |reply|
            reply_post = reply_posts[reply[:id]]
            next false if reply_post.blank?

            reply_post.association(:topic).target = post.topic
            guardian.can_see?(reply_post)
          end

        ToolHelpers.text_and_structured(
          post_id: post.id,
          mode: "reply_ids",
          replies: visible_replies,
          meta: {
            returned: visible_replies.length,
            exhaustive: false,
            upstream_bounded: "recursive descendants up to depth 1000",
          },
        )
      end
      private_class_method :reply_ids_result

      def self.direct_replies(post, after_post_number, request_context)
        after_post_number = [after_post_number.to_i, 1].max
        post_ids =
          post
            .replies
            .secured(request_context.guardian)
            .where(post_number: after_post_number + 1..)
            .order(:post_number)
            .limit(DIRECT_REPLIES_LIMIT)
            .pluck(:id)
        posts_for_ids(post.topic, post_ids, request_context)
      end
      private_class_method :direct_replies

      def self.reply_history(post, request_context)
        topic_view =
          TopicView.new(
            post.topic,
            request_context.user,
            include_suggested: false,
            include_related: false,
            reply_history_for: post.id,
          )
        topic_view.posts.select { |reply| request_context.guardian.can_see?(reply) }
      end
      private_class_method :reply_history

      def self.posts_for_ids(topic, post_ids, request_context)
        return [] if post_ids.empty?

        topic_view =
          TopicView.new(
            topic,
            request_context.user,
            post_ids:,
            include_related: false,
            include_suggested: false,
          )
        posts = topic_view.posts.index_by(&:id)
        post_ids.filter_map do |post_id|
          post = posts[post_id]
          post if request_context.guardian.can_see?(post)
        end
      end
      private_class_method :posts_for_ids
    end

    class ListLatestPosts
      REQUIRED_SCOPES = [Scopes::CONTENT_READ].freeze
      OUTPUT_SCHEMA =
        OutputSchema.object(posts: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)

      def self.call(arguments:, request_context:)
        before_post_id = arguments["before_post_id"]
        posts =
          LatestPostsQuery
            .new(user: request_context.user, guardian: request_context.guardian)
            .public_posts(before_post_id:)
            .to_a
        rows =
          (
            if arguments.fetch("replies_only", false)
              posts.select { |post| post.post_number > 1 }
            else
              posts
            end
          )

        ToolHelpers.text_and_structured(
          posts:
            rows.map do |post|
              ToolHelpers.evidence_post_json(
                post,
                excerpt: ToolHelpers.post_excerpt(post, request_context.guardian),
                include_raw: true,
              )
            end,
          meta: {
            before_post_id:,
            upstream_page_size: LatestPostsQuery::PAGE_SIZE,
            upstream_returned: posts.length,
            returned: rows.length,
            has_more: nil,
            page_was_full: posts.length == LatestPostsQuery::PAGE_SIZE,
            next_before_post_id: posts.last&.id,
            replies_only_projection: arguments.fetch("replies_only", false),
            anonymous_cache_seconds: 60,
          },
        )
      end
    end

    class GetTopicViewStats
      REQUIRED_SCOPES = [Scopes::CONTENT_READ].freeze
      OUTPUT_SCHEMA =
        OutputSchema.object(
          topic_id: OutputSchema::INTEGER,
          view_stats: OutputSchema::OBJECT_ARRAY,
          meta: OutputSchema::OBJECT,
        )

      def self.call(arguments:, request_context:)
        topic = Topic.find_by(id: arguments.fetch("topic_id"))
        if topic.blank? || !request_context.guardian.can_see?(topic)
          raise DiscourseMcp::ToolError, I18n.t("mcp.errors.topic_not_found")
        end
        ToolHelpers.ensure_private_message_scope!(topic, request_context, access: :read)

        from = arguments["from"] ? parse_date(arguments["from"]) : 30.days.ago.to_date
        to = arguments["to"] ? parse_date(arguments["to"]) : Date.current
        stats = TopicViewStatsQuery.call(topic:, guardian: request_context.guardian, from:, to:)
        rows =
          stats.map do |stat|
            {
              viewed_at: stat.viewed_at.iso8601,
              views: stat.anonymous_views + stat.logged_in_views,
            }
          end

        ToolHelpers.text_and_structured(
          topic_id: topic.id,
          view_stats: rows,
          meta: {
            from: arguments["from"],
            to: arguments["to"],
            default_range_days: arguments["from"] || arguments["to"] ? nil : 30,
            upstream_max_rows: TopicViewStatsQuery::MAX_STATS,
            returned: rows.length,
          },
        )
      end

      def self.parse_date(value)
        Date.iso8601(value)
      rescue Date::Error
        raise DiscourseMcp::ToolError, I18n.t("mcp.errors.invalid_date")
      end
      private_class_method :parse_date
    end

    class GetTopic
      REQUIRED_SCOPES = [Scopes::CONTENT_READ].freeze
      OUTPUT_SCHEMA =
        OutputSchema.object(
          id: OutputSchema::INTEGER,
          title: OutputSchema::STRING,
          slug: OutputSchema::STRING,
          category_id: OutputSchema::INTEGER_OR_NULL,
          tags: OutputSchema::STRING_ARRAY,
          posts_count: OutputSchema::INTEGER,
          created_at: OutputSchema::STRING,
          last_posted_at: OutputSchema::STRING_OR_NULL,
          closed: OutputSchema::BOOLEAN,
          archived: OutputSchema::BOOLEAN,
          url: OutputSchema::STRING,
          posts: OutputSchema::OBJECT_ARRAY,
          meta: OutputSchema::OBJECT,
        )

      def self.call(arguments:, request_context:)
        topic = Topic.find_by(id: arguments.fetch("topic_id").to_i)
        if topic.blank? || !request_context.guardian.can_see?(topic)
          raise DiscourseMcp::ToolError, I18n.t("mcp.errors.topic_not_found")
        end
        ToolHelpers.ensure_private_message_scope!(topic, request_context, access: :read)

        limit = arguments.fetch("post_limit", 5)
        start_post_number = arguments.fetch("start_post_number", 1)
        posts =
          request_context
            .guardian
            .filter_hidden_posts(
              Post.secured(request_context.guardian).joins(:topic),
              category: topic.category,
            )
            .where(topic_id: topic.id)
            .where(post_number: start_post_number..)
            .order(:post_number)
            .limit(limit + 1)
            .includes(:topic, :user)
            .to_a
        has_more = posts.length > limit
        posts = posts.first(limit)
        visible_tag_ids = ToolHelpers.visible_tag_ids([topic], request_context.guardian)
        result =
          ToolHelpers.topic_json(topic, request_context.guardian, visible_tag_ids:).merge(
            posts: posts.map { |post| ToolHelpers.evidence_post_json(post, include_raw: true) },
            meta: {
              start_post: start_post_number,
              returned: posts.length,
              has_more:,
            },
          )
        ToolHelpers.text_and_structured(result)
      end
    end

    class GetPost
      REQUIRED_SCOPES = [Scopes::CONTENT_READ].freeze
      OUTPUT_SCHEMA =
        OutputSchema.object(
          optional: %w[accepted_answer topic_accepted_answer],
          id: OutputSchema::INTEGER,
          topic_id: OutputSchema::INTEGER,
          topic_slug: OutputSchema::STRING_OR_NULL,
          post_number: OutputSchema::INTEGER,
          username: OutputSchema::STRING_OR_NULL,
          created_at: OutputSchema::STRING,
          raw: OutputSchema::STRING,
          truncated: OutputSchema::BOOLEAN,
          accepted_answer: OutputSchema::BOOLEAN_OR_NULL,
          topic_accepted_answer: OutputSchema::BOOLEAN_OR_NULL,
        )

      def self.call(arguments:, request_context:)
        post = ToolHelpers.visible_post!(arguments.fetch("post_id"), request_context)
        result =
          ToolHelpers.evidence_post_json(post, include_raw: true).slice(
            :id,
            :topic_id,
            :topic_slug,
            :post_number,
            :username,
            :created_at,
            :raw,
            :truncated,
            :accepted_answer,
            :topic_accepted_answer,
          )
        ToolHelpers.text_and_structured(result)
      end
    end

    class ListTopics
      REQUIRED_SCOPES = [Scopes::CONTENT_READ].freeze
      OUTPUT_SCHEMA = OutputSchema.object(topics: OutputSchema::OBJECT_ARRAY)

      def self.call(arguments:, request_context:)
        limit = arguments.fetch("limit", 30).to_i.clamp(1, 50)
        topics = TopicQuery.new(request_context.user).list_latest.topics.first(limit)
        ActiveRecord::Associations::Preloader.new(records: topics, associations: :tags).call
        visible_tag_ids = ToolHelpers.visible_tag_ids(topics, request_context.guardian)
        ToolHelpers.text_and_structured(
          topics:
            topics.map do |topic|
              ToolHelpers.topic_json(topic, request_context.guardian, visible_tag_ids:)
            end,
        )
      end
    end

    class ListCategories
      REQUIRED_SCOPES = [Scopes::CONTENT_READ].freeze
      OUTPUT_SCHEMA = OutputSchema.object(categories: OutputSchema::OBJECT_ARRAY)

      def self.call(arguments:, request_context:)
        categories = Category.secured(request_context.guardian).order(:position, :id).limit(500)
        ToolHelpers.text_and_structured(
          categories:
            categories.map do |category|
              {
                id: category.id,
                name: category.name,
                slug: category.slug,
                parent_category_id: category.parent_category_id,
                topic_count: category.topic_count,
              }
            end,
        )
      end
    end

    class ListTags
      REQUIRED_SCOPES = [Scopes::CONTENT_READ].freeze
      OUTPUT_SCHEMA = OutputSchema.object(tags: OutputSchema::OBJECT_ARRAY)

      def self.call(arguments:, request_context:)
        column = Tag.topic_count_column(request_context.guardian)
        tags = Tag.order(column => :desc).limit(arguments.fetch("limit", 100).to_i.clamp(1, 200))
        visible = DiscourseTagging.filter_visible(tags, request_context.guardian)
        ToolHelpers.text_and_structured(
          tags:
            visible.map do |tag|
              { id: tag.id, name: tag.name, topic_count: tag.public_send(column) }
            end,
        )
      end
    end
  end
end