A platform for community discussion. Free, open, simple.
DEV: Add moderation and site setting tools to the MCP server (#43772)
Natalie Tay3d334f4b40f7
diff --git a/app/serializers/reviewable_score_serializer.rb b/app/serializers/reviewable_score_serializer.rbindex 2f14746993f..3bf60409b19 100644--- a/app/serializers/reviewable_score_serializer.rb+++ b/app/serializers/reviewable_score_serializer.rb@@ -56,6 +56,9 @@ class ReviewableScoreSerializer < ApplicationSerializerdef include_reviewable_conversation?return false if object.meta_topic.blank?+ if object.meta_topic.private_message? && @options[:include_private_conversations] == false+ return false+ endscope&.can_see?(object.meta_topic) || object.notify_moderators_flag_message?enddiff --git a/app/services/site_setting/update.rb b/app/services/site_setting/update.rbindex 900b8845fbd..42a910fca66 100644--- a/app/services/site_setting/update.rb+++ b/app/services/site_setting/update.rb@@ -3,11 +3,15 @@class SiteSetting::Updateinclude Service::Base+ class Conflict < StandardError+ end+Setting = Struct.new(:name, :value, :backfill, :change)options doattribute :allow_changing_hidden, :array, default: []attribute :overridden_setting_names, default: -> { {} }+ attribute :expected_values, default: -> { {} }endpolicy :current_user_is_admin@@ -70,9 +74,13 @@ class SiteSetting::Updatepolicy :settings_are_configurable, class_name: SiteSetting::Policy::SettingsAreConfigurabletry do- transaction do- step :save- step :backfill+ lock do+ step :ensure_expected_values++ transaction do+ step :save+ step :backfill+ endendend@@ -82,6 +90,23 @@ class SiteSetting::Updateguardian.is_admin?end+ def ensure_expected_values(options:)+ options.expected_values.each do |name, expected_value|+ stored_setting = SiteSetting.provider.find(name)+ current_value =+ if stored_setting+ SiteSetting.type_supervisor.to_rb_value(+ name,+ stored_setting.value,+ stored_setting.data_type,+ )+ else+ SiteSetting.public_send(name)+ end+ raise Conflict if current_value.to_s != expected_value.to_s+ end+ end+def save(params:, options:, guardian:)params.settings.each do |setting|detailed_message =diff --git a/config/locales/server.en.yml b/config/locales/server.en.ymlindex c64df40e405..ae81c7099b2 100644--- a/config/locales/server.en.yml+++ b/config/locales/server.en.yml@@ -13,6 +13,8 @@ en:filter_required: "A nonblank filter is required for the filtered view"invalid_post_selection: "The post selection options are invalid"invalid_search_query: "The search query is invalid"+ invalid_reviewable_status: "The reviewable status is invalid"+ invalid_reviewable_type: "The reviewable type is invalid"group_mailbox_sent: "Group private-message mailboxes do not support sent messages"invalid_upload_data: "The upload data is not valid base64"invalid_upload_source: "Provide either base64 data with a filename or one remote URL"@@ -24,6 +26,26 @@ en:private_message_not_found: "Personal message not found"private_message_recipient_required: "At least one private-message recipient is required"private_message_single_recipient: "Provide exactly one user, group, or email recipient"+ post_revision_not_found: "Post revision not found"+ reviewable_action_failed: "The reviewable action failed"+ reviewable_action_unavailable: "The reviewable action is no longer available"+ reviewable_confirmation_required: "Explicit confirmation is required for a reviewable action"+ reviewable_conflict: "The reviewable changed since it was read"+ reviewable_fields_unavailable: "These fields are not accepted by the reviewable action: %{fields}"+ reviewable_not_found: "Reviewable not found"+ reviewable_reject_reason_required: "A reject reason is required for this action"+ site_setting_confirmation_required: "This site setting requires explicit confirmation"+ site_setting_change_confirmation_required: "Explicit confirmation is required to change a site setting"+ site_setting_conflict: "The site setting changed since it was read"+ site_setting_dependency: "These site setting dependencies are not satisfied: %{settings}"+ site_setting_no_change: "The requested site setting change has no effect"+ site_setting_not_found: "Site setting not found"+ site_setting_sensitive: "Sensitive site settings cannot be read or changed by this tool"+ site_setting_type_unsupported: "This site setting type cannot be changed by this tool"+ site_setting_update_failed: "The site setting could not be updated"+ site_setting_value_forbidden: "Do not provide a value when resetting a site setting"+ site_setting_value_required: "Provide a value when setting a site setting"+ site_setting_verification_failed: "The site setting update could not be verified"topic_not_found: "Topic not found"topic_update_required: "Provide at least one topic field to update"top_period_only_for_top_view: "Top period is only supported by the top view"diff --git a/lib/discourse_mcp.rb b/lib/discourse_mcp.rbindex 054124c36ff..8f6b9f6ecca 100644--- a/lib/discourse_mcp.rb+++ b/lib/discourse_mcp.rb@@ -10,6 +10,10 @@ module DiscourseMcpDRAFTS_WRITE = "mcp:drafts:write"PRIVATE_MESSAGES_READ = "mcp:private-messages:read"PRIVATE_MESSAGES_WRITE = "mcp:private-messages:write"+ MODERATION_READ = "mcp:moderation:read"+ MODERATION_WRITE = "mcp:moderation:write"+ SITE_SETTINGS_READ = "mcp:site-settings:read"+ SITE_SETTINGS_WRITE = "mcp:site-settings:write"endPROTOCOL_VERSION = "2026-07-28"diff --git a/lib/discourse_mcp/core_primitives.rb b/lib/discourse_mcp/core_primitives.rbindex df3c82369ca..3685d093d1d 100644--- a/lib/discourse_mcp/core_primitives.rb+++ b/lib/discourse_mcp/core_primitives.rb@@ -65,6 +65,8 @@ module DiscourseMcpregistry = DiscourseMcp.registryregister_read_tools(registry)register_write_tools(registry)+ register_moderation_tools(registry)+ register_site_setting_tools(registry)register_resources(registry)register_prompts(registry)end@@ -290,11 +292,11 @@ module DiscourseMcp},from: {type: "string",- pattern: "\\A[0-9]{4}-[0-9]{2}-[0-9]{2}\\z",+ pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",},to: {type: "string",- pattern: "\\A[0-9]{4}-[0-9]{2}-[0-9]{2}\\z",+ pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",},},required: %w[topic_id],@@ -318,7 +320,7 @@ module DiscourseMcp},order: {type: "string",- pattern: "\\A[a-z0-9_]+\\z",+ pattern: "^[a-z0-9_]+$",},ascending: {type: "boolean",@@ -1152,6 +1154,343 @@ module DiscourseMcp)end+ def register_moderation_tools(registry)+ register_tool(+ registry,+ "discourse_get_review_queue_count",+ title: "Get review queue count",+ description:+ "Returns the number of pending reviewable records visible to the authenticated reviewer.",+ implementation: Tools::GetReviewQueueCount,+ annotations: READ_ONLY,+ risk: :moderation,+ )+ register_tool(+ registry,+ "discourse_list_reviewables",+ title: "List reviewables",+ description:+ "Lists reviewable records visible to the authenticated reviewer, including their current actions.",+ implementation: Tools::ListReviewables,+ input_schema:+ object_schema(+ {+ offset: {+ type: "integer",+ minimum: 0,+ default: 0,+ },+ status: {+ type: "string",+ enum: Tools::ModerationSupport::STATUSES,+ default: "pending",+ },+ type: {+ type: "string",+ minLength: 1,+ maxLength: 200,+ },+ topic_id: {+ type: "integer",+ minimum: 1,+ },+ category_id: {+ type: "integer",+ minimum: 1,+ },+ priority: {+ type: "string",+ enum: %w[low medium high],+ },+ username: {+ type: "string",+ minLength: 1,+ maxLength: 60,+ },+ reviewed_by: {+ type: "string",+ minLength: 1,+ maxLength: 60,+ },+ claimed_by: {+ type: "string",+ minLength: 1,+ maxLength: 60,+ },+ flagged_by: {+ type: "string",+ minLength: 1,+ maxLength: 60,+ },+ from_date: {+ type: "string",+ format: "date-time",+ },+ to_date: {+ type: "string",+ format: "date-time",+ },+ sort_order: {+ type: "string",+ enum: %w[score score_asc created_at created_at_asc],+ },+ score_type: {+ type: "string",+ minLength: 1,+ maxLength: 200,+ },+ },+ ),+ annotations: READ_ONLY,+ risk: :moderation,+ )+ register_tool(+ registry,+ "discourse_list_reviewable_topics",+ title: "List reviewable topics",+ description:+ "Lists topic-level signals from pending reviewables visible to the authenticated reviewer.",+ implementation: Tools::ListReviewableTopics,+ input_schema:+ object_schema(+ {+ offset: {+ type: "integer",+ minimum: 0,+ default: 0,+ },+ limit: {+ type: "integer",+ minimum: 1,+ maximum: 100,+ default: 100,+ },+ },+ ),+ annotations: READ_ONLY,+ risk: :moderation,+ )+ register_tool(+ registry,+ "discourse_get_reviewable",+ title: "Get reviewable",+ description:+ "Returns one visible reviewable with its current version, evidence, and available actions.",+ implementation: Tools::GetReviewable,+ input_schema:+ object_schema(+ {+ reviewable_id: {+ type: "integer",+ minimum: 1,+ },+ include_explanation: {+ type: "boolean",+ },+ },+ required: %w[reviewable_id],+ ),+ annotations: READ_ONLY,+ risk: :moderation,+ )+ register_tool(+ registry,+ "discourse_get_user_moderation_summary",+ title: "Get user moderation summary",+ description: "Returns staff-visible moderation counters for a user.",+ implementation: Tools::GetUserModerationSummary,+ input_schema:+ object_schema(+ { username: { type: "string", minLength: 1, maxLength: 60 } },+ required: %w[username],+ ),+ annotations: READ_ONLY,+ risk: :moderation,+ )+ register_tool(+ registry,+ "discourse_get_post_revision",+ title: "Get post revision",+ description: "Returns a post revision visible to the authenticated reviewer.",+ implementation: Tools::GetPostRevision,+ input_schema:+ object_schema(+ {+ post_id: {+ type: "integer",+ minimum: 1,+ },+ revision: {+ oneOf: [{ const: "latest" }, { type: "integer", minimum: 2 }],+ default: "latest",+ },+ },+ required: %w[post_id],+ ),+ annotations: READ_ONLY,+ risk: :moderation,+ )+ register_tool(+ registry,+ "discourse_perform_reviewable_action",+ title: "Perform reviewable action",+ description:+ "Performs one currently available action on a visible reviewable after a fresh permission check.",+ implementation: Tools::PerformReviewableAction,+ input_schema:+ object_schema(+ {+ reviewable_id: {+ type: "integer",+ minimum: 1,+ },+ action_id: {+ type: "string",+ minLength: 1,+ maxLength: 200,+ },+ expected_version: {+ type: "integer",+ minimum: 0,+ },+ additional_fields: {+ type: "object",+ maxProperties: 20,+ propertyNames: {+ pattern: "^[a-z0-9_]+$",+ },+ additionalProperties: {+ oneOf: [+ { type: "string", maxLength: 2_000 },+ { type: "boolean" },+ { type: "integer" },+ { type: "number" },+ ],+ },+ },+ confirm: {+ const: true,+ },+ },+ required: %w[reviewable_id action_id confirm],+ ),+ annotations: {+ readOnlyHint: false,+ destructiveHint: true,+ idempotentHint: false,+ openWorldHint: true,+ },+ risk: :moderation,+ )+ end++ def register_site_setting_tools(registry)+ register_tool(+ registry,+ "discourse_list_site_settings",+ title: "List site settings",+ description:+ "Lists admin-visible site settings while masking secret and credential-like values.",+ implementation: Tools::ListSiteSettings,+ input_schema:+ object_schema(+ {+ categories: {+ type: "array",+ items: {+ type: "string",+ minLength: 1,+ maxLength: 200,+ },+ maxItems: 50,+ },+ plugin: {+ type: "string",+ minLength: 1,+ maxLength: 200,+ },+ names: {+ type: "array",+ items: {+ type: "string",+ pattern: "^[a-z0-9_]+$",+ maxLength: 200,+ },+ maxItems: 100,+ },+ overridden_only: {+ type: "boolean",+ },+ offset: {+ type: "integer",+ minimum: 0,+ default: 0,+ },+ limit: {+ type: "integer",+ minimum: 1,+ maximum: 500,+ default: 100,+ },+ },+ ),+ annotations: READ_ONLY,+ risk: :administration,+ )+ setting_value_schema = {+ oneOf: [+ { type: "string", maxLength: 20_000 },+ { type: "number" },+ { type: "boolean" },+ {+ type: "array",+ items: {+ oneOf: [{ type: "string", maxLength: 2_000 }, { type: "number" }],+ },+ maxItems: 200,+ },+ ],+ }+ register_tool(+ registry,+ "discourse_update_site_setting",+ title: "Update site setting",+ description:+ "Sets or resets one ordinary site setting after a current-value check and explicit confirmation.",+ implementation: Tools::UpdateSiteSetting,+ input_schema:+ object_schema(+ {+ setting: {+ type: "string",+ pattern: "^[a-z0-9_]+$",+ maxLength: 200,+ },+ operation: {+ type: "string",+ enum: %w[set reset_to_default],+ },+ value: setting_value_schema,+ expected_current_value: setting_value_schema,+ confirm_change: {+ const: true,+ },+ confirm_required_setting: {+ const: true,+ },+ },+ required: %w[setting operation expected_current_value confirm_change],+ ),+ annotations: {+ readOnlyHint: false,+ destructiveHint: true,+ idempotentHint: true,+ openWorldHint: true,+ },+ risk: :administration,+ )+ end+def register_resources(registry)register_resource_template(registry,@@ -1161,7 +1500,7 @@ module DiscourseMcpimplementation: Resources::Topic,input_schema:object_schema(- { uri: { type: "string", pattern: "\\Adiscourse://topic/[0-9]+\\z" } },+ { uri: { type: "string", pattern: "^discourse://topic/[0-9]+$" } },required: %w[uri],),annotations: READ_ONLY,@@ -1174,7 +1513,7 @@ module DiscourseMcpimplementation: Resources::Post,input_schema:object_schema(- { uri: { type: "string", pattern: "\\Adiscourse://post/[0-9]+\\z" } },+ { uri: { type: "string", pattern: "^discourse://post/[0-9]+$" } },required: %w[uri],),annotations: READ_ONLY,diff --git a/lib/discourse_mcp/core_tools.rb b/lib/discourse_mcp/core_tools.rbindex 054a2261cf4..a4a9be5b5a8 100644--- a/lib/discourse_mcp/core_tools.rb+++ b/lib/discourse_mcp/core_tools.rb@@ -11,3 +11,5 @@ require "discourse_mcp/tools/notifications"require "discourse_mcp/tools/drafts"require "discourse_mcp/tools/uploads"require "discourse_mcp/tools/private_messages"+require "discourse_mcp/tools/moderation"+require "discourse_mcp/tools/site_settings"diff --git a/lib/discourse_mcp/tools/moderation.rb b/lib/discourse_mcp/tools/moderation.rbnew file mode 100644index 00000000000..ed3f86d2940--- /dev/null+++ b/lib/discourse_mcp/tools/moderation.rb@@ -0,0 +1,458 @@+# frozen_string_literal: true++module DiscourseMcp+ module Tools+ module ModerationSupport+ PER_PAGE = 10+ STATUSES = %w[pending approved rejected ignored deleted reviewed all].freeze+ FILTER_KEYS = %w[+ priority+ username+ reviewed_by+ claimed_by+ type+ sort_order+ flagged_by+ score_type+ ].freeze+ CORE_ADDITIONAL_FIELDS = {+ "revise_and_reject_post" => %w[revise_reason revise_feedback revise_custom_reason],+ }.freeze++ module_function++ def ensure_queue_access!(guardian)+ guardian.ensure_can_see_review_queue!+ end++ def without_private_messages(scope, request_context)+ return scope if request_context.has_scopes?(Scopes::PRIVATE_MESSAGES_READ)++ private_message_topic_ids =+ Topic.unscoped.where(archetype: Archetype.private_message).select(:id)+ scope.where(topic_id: nil).or(scope.where.not(topic_id: private_message_topic_ids))+ end++ def ensure_private_message_scope!(reviewable, request_context, access:)+ topic = reviewable.topic || Topic.unscoped.find_by(id: reviewable.topic_id)+ return if topic.blank?++ ToolHelpers.ensure_private_message_scope!(topic, request_context, access:)+ end++ def with_deleted_content(guardian, &block)+ return yield unless guardian.is_staff?++ Post.unscoped { Topic.unscoped { PostAction.unscoped(&block) } }+ end++ def list_filters(arguments)+ status = arguments.fetch("status", "pending")+ if !STATUSES.include?(status)+ raise ToolError, I18n.t("mcp.errors.invalid_reviewable_status")+ end++ type = arguments["type"]+ if type.present? && !Reviewable.valid_filter_type?(type)+ raise ToolError, I18n.t("mcp.errors.invalid_reviewable_type")+ end++ filters = {+ status: status.to_sym,+ topic_id: arguments["topic_id"],+ category_id: arguments["category_id"],+ from_date: parse_time(arguments["from_date"]),+ to_date: parse_time(arguments["to_date"]),+ }+ FILTER_KEYS.each { |key| filters[key.to_sym] = arguments[key] }+ filters.compact+ end++ def parse_time(value)+ return if value.blank?++ Time.zone.iso8601(value)+ rescue ArgumentError+ raise ToolError, I18n.t("mcp.errors.invalid_date")+ end++ def serialize_reviewables(reviewables, request_context)+ guardian = request_context.guardian+ claimed_topics =+ ReviewableClaimedTopic.claimed_hash(reviewables.map(&:topic_id).compact.uniq)+ Reviewable.preload_author_penalties(reviewables)+ side_loads = {}+ serialized =+ reviewables.map do |reviewable|+ reviewable+ .serializer+ .new(+ reviewable,+ root: nil,+ hash: side_loads,+ scope: guardian,+ claimed_topics:,+ include_private_conversations:+ request_context.has_scopes?(Scopes::PRIVATE_MESSAGES_READ),+ )+ .as_json+ end++ side_loads.each_value { |value| value.uniq! if value.is_a?(Array) }+ [bounded(serialized), bounded(side_loads).deep_symbolize_keys]+ end++ def serialize_reviewable(reviewable, request_context)+ reviewables, side_loads = serialize_reviewables([reviewable], request_context)+ { reviewable: reviewables.first, **side_loads }+ end++ def bounded(value)+ case value+ when String+ value.first(ToolHelpers::MAX_READ_LENGTH)+ when Array+ value.first(100).map { |item| bounded(item) }+ when Hash+ value.to_h { |key, item| [key, bounded(item)] }+ else+ value+ end+ end++ def find_reviewable!(reviewable_id, user)+ Reviewable.viewable_by(user).find_by(id: reviewable_id) or+ raise ToolError, I18n.t("mcp.errors.reviewable_not_found")+ end++ def find_visible_post!(post_id, guardian)+ post = Post.with_deleted.find_by(id: post_id)+ topic = Topic.with_deleted.find_by(id: post&.topic_id)+ post.association(:topic).target = topic if post && topic++ deleted = post&.deleted_at.present? || topic&.deleted_at.present?+ if post.blank? || topic.blank? || (deleted && !guardian.can_moderate_topic?(topic)) ||+ !guardian.can_see?(post)+ raise ToolError, I18n.t("mcp.errors.post_not_found")+ end++ post+ end++ def available_actions(reviewable, guardian)+ reviewable.actions_for(guardian).bundles.flat_map(&:actions).uniq+ end++ def find_action!(reviewable, guardian, action_id)+ actions = available_actions(reviewable, guardian)+ action = actions.find { |candidate| candidate.id.to_s == action_id }+ action ||= actions.find { |candidate| candidate.server_action.to_s == action_id }+ action or raise ToolError, I18n.t("mcp.errors.reviewable_action_unavailable")+ end++ def action_arguments(reviewable, action, supplied)+ server_action = action.server_action.to_s+ allowed = Array(CORE_ADDITIONAL_FIELDS[server_action])+ allowed += %w[reject_reason send_email] if reviewable.is_a?(ReviewableUser)+ allowed +=+ DiscoursePluginRegistry+ .reviewable_params+ .select { |entry| reviewable.type == entry[:type].to_s.classify }+ .map { |entry| entry[:param].to_s }+ allowed.uniq!++ disallowed = supplied.keys - allowed+ if disallowed.present?+ raise ToolError,+ I18n.t("mcp.errors.reviewable_fields_unavailable", fields: disallowed.join(", "))+ end+ if action.require_reject_reason && supplied["reject_reason"].blank?+ raise ToolError, I18n.t("mcp.errors.reviewable_reject_reason_required")+ end++ result = supplied.symbolize_keys+ result[:send_email] = true if reviewable.is_a?(ReviewableUser) && !result.key?(:send_email)+ result+ end++ def ensure_claim_allows_action!(reviewable, user)+ return if SiteSetting.reviewable_claiming == "disabled" || reviewable.topic_id.blank?++ claimed_by_id = ReviewableClaimedTopic.where(topic_id: reviewable.topic_id).pick(:user_id)+ if SiteSetting.reviewable_claiming == "required" && claimed_by_id.blank?+ raise ToolError, I18n.t("reviewables.must_claim")+ end+ if claimed_by_id && claimed_by_id != user.id+ raise ToolError, I18n.t("reviewables.user_claimed")+ end+ end+ end++ class GetReviewQueueCount+ REQUIRED_SCOPES = [Scopes::MODERATION_READ].freeze+ OUTPUT_SCHEMA =+ OutputSchema.object(+ count: OutputSchema::INTEGER,+ unit: OutputSchema::STRING,+ status: OutputSchema::STRING,+ scope: OutputSchema::STRING,+ )++ def self.call(arguments:, request_context:)+ guardian = request_context.guardian+ ModerationSupport.ensure_queue_access!(guardian)+ scope = Reviewable.list_for(request_context.user)+ scope = ModerationSupport.without_private_messages(scope, request_context)+ ToolHelpers.text_and_structured(+ count: scope.count,+ unit: "pending_reviewable_queue_items",+ status: "pending",+ scope: "visible_to_authenticated_user",+ )+ end+ end++ class ListReviewables+ REQUIRED_SCOPES = [Scopes::MODERATION_READ].freeze+ OUTPUT_SCHEMA = OutputSchema::OBJECT++ def self.call(arguments:, request_context:)+ guardian = request_context.guardian+ ModerationSupport.ensure_queue_access!(guardian)+ offset = arguments.fetch("offset", 0)+ filters = ModerationSupport.list_filters(arguments)++ ModerationSupport.with_deleted_content(guardian) do+ query = Reviewable.list_for(request_context.user, **filters)+ query = ModerationSupport.without_private_messages(query, request_context)+ total = query.count+ reviewables = query.limit(ModerationSupport::PER_PAGE).offset(offset).to_a+ rows, side_loads = ModerationSupport.serialize_reviewables(reviewables, request_context)+ has_more = offset + rows.length < total+ ToolHelpers.text_and_structured(+ reviewables: rows,+ **side_loads,+ meta: {+ offset:,+ per_page: ModerationSupport::PER_PAGE,+ returned: rows.length,+ total:,+ has_more:,+ next_offset: has_more ? offset + ModerationSupport::PER_PAGE : nil,+ status: filters[:status].to_s,+ scope: "visible_to_authenticated_user",+ },+ )+ end+ end+ end++ class ListReviewableTopics+ REQUIRED_SCOPES = [Scopes::MODERATION_READ].freeze+ OUTPUT_SCHEMA =+ OutputSchema.object(topics: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)++ def self.call(arguments:, request_context:)+ guardian = request_context.guardian+ ModerationSupport.ensure_queue_access!(guardian)+ offset = arguments.fetch("offset", 0)+ limit = arguments.fetch("limit", 100)+ reviewable_scope =+ ModerationSupport+ .without_private_messages(+ Reviewable.viewable_by(request_context.user, preload: false),+ request_context,+ )+ .pending+ .where("score >= ?", Reviewable.min_score_for_priority)+ visible_topic_ids =+ reviewable_scope.reorder(nil).where.not(topic_id: nil).select(:topic_id).distinct+ topic_scope = Topic.where(id: visible_topic_ids).order(reviewable_score: :desc, id: :desc)+ total = topic_scope.count+ topics = topic_scope.offset(offset).limit(limit).to_a+ topic_ids = topics.map(&:id)+ serialized_stats = topic_ids.index_with { { count: 0, unique_users: 0 } }+ if topic_ids.present?+ visible_reviewable_ids =+ reviewable_scope.reorder(nil).where(topic_id: topic_ids).select(:id)+ ReviewableScore+ .joins(:reviewable)+ .where(reviewable_id: visible_reviewable_ids)+ .group("reviewables.topic_id")+ .pluck(+ "reviewables.topic_id",+ Arel.sql("COUNT(*)"),+ Arel.sql("COUNT(DISTINCT reviewable_scores.user_id)"),+ )+ .each do |topic_id, count, unique_users|+ serialized_stats[topic_id] = { count:, unique_users: }+ end+ end+ claimed_topics = ReviewableClaimedTopic.claimed_hash(topic_ids)+ serialized_topics =+ topics.map do |topic|+ ReviewableTopicSerializer.new(+ topic,+ root: false,+ scope: guardian,+ stats: serialized_stats,+ claimed_topics:,+ ).as_json+ end+ has_more = offset + serialized_topics.length < total++ ToolHelpers.text_and_structured(+ topics: ModerationSupport.bounded(serialized_topics),+ meta: {+ exhaustive: false,+ offset:,+ limit:,+ returned: serialized_topics.length,+ total:,+ has_more:,+ next_offset: has_more ? offset + serialized_topics.length : nil,+ scope: "pending topics at or above the review priority threshold",+ },+ )+ end+ end++ class GetReviewable+ REQUIRED_SCOPES = [Scopes::MODERATION_READ].freeze+ OUTPUT_SCHEMA = OutputSchema::OBJECT++ def self.call(arguments:, request_context:)+ guardian = request_context.guardian+ ModerationSupport.ensure_queue_access!(guardian)+ ModerationSupport.with_deleted_content(guardian) do+ reviewable =+ ModerationSupport.find_reviewable!(+ arguments.fetch("reviewable_id"),+ request_context.user,+ )+ ModerationSupport.ensure_private_message_scope!(+ reviewable,+ request_context,+ access: :read,+ )+ result = ModerationSupport.serialize_reviewable(reviewable, request_context)+ result[:explanation] = reviewable.explain_score if arguments["include_explanation"]+ ToolHelpers.text_and_structured(ModerationSupport.bounded(result))+ end+ end+ end++ class GetUserModerationSummary+ REQUIRED_SCOPES = [Scopes::MODERATION_READ].freeze+ OUTPUT_SCHEMA =+ OutputSchema.object(+ username: OutputSchema::STRING,+ deleted_posts: OutputSchema::INTEGER,+ flags_received: OutputSchema::INTEGER,+ flags_given: OutputSchema::INTEGER,+ silencings: OutputSchema::INTEGER,+ suspensions: OutputSchema::INTEGER,+ warnings_received: OutputSchema::INTEGER,+ rejected_posts: OutputSchema::INTEGER,+ )++ def self.call(arguments:, request_context:)+ user = User.find_by_username(arguments.fetch("username"))+ raise ToolError, I18n.t("mcp.errors.user_not_found") if user.blank?++ request_context.guardian.ensure_can_see_staff_info!(user)+ ToolHelpers.text_and_structured(+ username: user.username,+ deleted_posts: user.number_of_deleted_posts,+ flags_received: user.number_of_flags,+ flags_given: user.number_of_flags_given,+ silencings: user.number_of_silencings,+ suspensions: user.number_of_suspensions,+ warnings_received: user.warnings_received_count,+ rejected_posts: user.number_of_rejected_posts,+ )+ end+ end++ class GetPostRevision+ REQUIRED_SCOPES = [Scopes::MODERATION_READ].freeze+ OUTPUT_SCHEMA = OutputSchema::OBJECT++ def self.call(arguments:, request_context:)+ guardian = request_context.guardian+ ModerationSupport.ensure_queue_access!(guardian)+ post = ModerationSupport.find_visible_post!(arguments.fetch("post_id"), guardian)+ ToolHelpers.ensure_private_message_scope!(post.topic, request_context, access: :read)++ finder = PostRevision.where(post_id: post.id)+ finder = finder.where(hidden: false) if !guardian.can_view_hidden_post_revisions?+ requested_revision = arguments.fetch("revision", "latest")+ post_revision =+ if requested_revision == "latest"+ finder.order(:number).last+ else+ finder.find_by(number: requested_revision)+ end+ raise ToolError, I18n.t("mcp.errors.post_revision_not_found") if post_revision.blank?++ post_revision.post = post+ guardian.ensure_can_see!(post_revision)+ result =+ PostRevisionSerializer+ .new(post_revision, root: false, scope: guardian)+ .as_json+ .deep_symbolize_keys+ ToolHelpers.text_and_structured(ModerationSupport.bounded(result))+ end+ end++ class PerformReviewableAction+ REQUIRED_SCOPES = [Scopes::MODERATION_WRITE].freeze+ OUTPUT_SCHEMA = OutputSchema::OBJECT++ def self.call(arguments:, request_context:)+ guardian = request_context.guardian+ ModerationSupport.ensure_queue_access!(guardian)+ if arguments["confirm"] != true+ raise ToolError, I18n.t("mcp.errors.reviewable_confirmation_required")+ end+ reviewable =+ ModerationSupport.find_reviewable!(arguments.fetch("reviewable_id"), request_context.user)+ ModerationSupport.ensure_private_message_scope!(reviewable, request_context, access: :read)+ ModerationSupport.ensure_private_message_scope!(reviewable, request_context, access: :write)+ ModerationSupport.ensure_claim_allows_action!(reviewable, request_context.user)+ action = ModerationSupport.find_action!(reviewable, guardian, arguments.fetch("action_id"))+ if arguments.key?("expected_version") && arguments["expected_version"] != reviewable.version+ raise ToolError, I18n.t("mcp.errors.reviewable_conflict")+ end+ additional_fields = arguments.fetch("additional_fields", {})+ action_arguments =+ ModerationSupport.action_arguments(reviewable, action, additional_fields).merge(+ version: reviewable.version,+ guardian:,+ )++ result =+ reviewable.perform(request_context.user, action.server_action.to_sym, action_arguments)+ if !result.success?+ raise ToolError,+ result.errors&.full_messages&.join(", ").presence ||+ I18n.t("mcp.errors.reviewable_action_failed")+ end++ serialized =+ ReviewablePerformResultSerializer.new(result, root: false, scope: guardian).as_json+ ToolHelpers.text_and_structured(+ ModerationSupport+ .bounded(serialized)+ .deep_symbolize_keys+ .merge(reviewable_id: reviewable.id),+ )+ rescue Reviewable::InvalidAction+ raise ToolError, I18n.t("mcp.errors.reviewable_action_unavailable")+ rescue Reviewable::UpdateConflict+ raise ToolError, I18n.t("mcp.errors.reviewable_conflict")+ end+ end+ end+enddiff --git a/lib/discourse_mcp/tools/site_settings.rb b/lib/discourse_mcp/tools/site_settings.rbnew file mode 100644index 00000000000..9fe77e765b4--- /dev/null+++ b/lib/discourse_mcp/tools/site_settings.rb@@ -0,0 +1,295 @@+# frozen_string_literal: true++module DiscourseMcp+ module Tools+ module SiteSettingSupport+ CREDENTIAL_NAME =+ /(?:\A|_)(?:secret|token|password|passphrase|private_key|access_keys?|api_keys?|credentials?)(?:\z|_)/i+ UNSUPPORTED_TYPES = %w[upload uploaded_image_list uploaded-image-list objects].freeze+ UPDATE_POLICIES = %i[+ settings_are_not_deprecated+ settings_are_unshadowed_globally+ settings_are_visible+ settings_are_configurable+ ].freeze++ module_function++ def ensure_admin!(guardian)+ guardian.ensure_is_admin!+ end++ def settings(arguments = {}, include_hidden: false)+ SiteSetting.all_settings(+ include_hidden:,+ filter_categories: arguments["categories"],+ filter_plugin: arguments["plugin"],+ filter_names: arguments["names"],+ )+ end++ def exact_setting(name)+ settings({ "names" => [name] }).reverse.find { |setting| setting[:setting].to_s == name }+ end++ def blocked?(setting)+ setting[:secret] || setting[:setting].to_s.match?(CREDENTIAL_NAME)+ end++ def unsupported_type?(setting)+ setting[:themeable] == true || UNSUPPORTED_TYPES.include?(setting[:type].to_s)+ end++ def project(setting)+ blocked = blocked?(setting)+ {+ setting: setting[:setting].to_s,+ humanized_name: setting[:humanized_name].to_s.first(500),+ description: setting[:description].to_s.first(4_000),+ category: setting[:category],+ primary_area: setting[:primary_area],+ plugin: setting[:plugin],+ type: setting[:type].to_s,+ value: blocked ? nil : setting[:value],+ default: blocked ? nil : setting[:default],+ secret: blocked,+ overridden: setting[:value].to_s != setting[:default].to_s,+ valid_values: bounded_collection(setting[:valid_values]),+ min: setting[:min],+ max: setting[:max],+ mandatory_values: bounded_collection(setting[:mandatory_values]),+ requires_confirmation: setting[:requires_confirmation].present?,+ depends_on: Array(setting[:depends_on]).first(50).map(&:to_s),+ depends_behavior: setting[:depends_behavior]&.to_s,+ depends_on_values: bounded_hash(setting[:depends_on_values]),+ themeable: setting[:themeable] == true,+ editable_by_this_tool: !blocked && !unsupported_type?(setting),+ }+ end++ def bounded_collection(value)+ return [] if !value.is_a?(Array)++ value+ .first(200)+ .map do |item|+ if item.is_a?(Hash)+ item+ .slice(:id, :name, :value, "id", "name", "value")+ .transform_values { |entry| entry.to_s.first(1_000) }+ else+ item.to_s.first(1_000)+ end+ end+ end++ def bounded_hash(value)+ return {} if !value.is_a?(Hash)++ value+ .first(50)+ .to_h do |key, item|+ [key.to_s.first(200), Array(item).first(50).map { |entry| entry.to_s.first(1_000) }]+ end+ end++ def normalize(value)+ case value+ when Array+ value.map(&:to_s).join("|")+ when TrueClass+ "true"+ when FalseClass+ "false"+ else+ value.to_s+ end+ end++ def serialize(value)+ value.is_a?(Array) ? value.map(&:to_s).join("|") : value+ end++ def ensure_dependencies!(setting)+ dependencies = Array(setting[:depends_on]).map(&:to_s)+ return {} if dependencies.empty?++ definitions =+ settings({ "names" => dependencies }, include_hidden: true).index_by do |item|+ item[:setting].to_s+ end+ allowed_values = setting[:depends_on_values].is_a?(Hash) ? setting[:depends_on_values] : {}+ unsatisfied =+ dependencies.reject do |name|+ definition = definitions[name]+ next false if definition.blank?++ allowed = allowed_values[name] || allowed_values[name.to_sym]+ if allowed+ Array(allowed).map(&:to_s).include?(definition[:value].to_s)+ else+ %w[true 1 yes].include?(definition[:value].to_s.downcase)+ end+ end+ if unsatisfied.present?+ raise ToolError,+ I18n.t("mcp.errors.site_setting_dependency", settings: unsatisfied.join(", "))+ end++ dependencies.to_h { |name| [name, definitions.fetch(name)[:value]] }+ end++ def update!(guardian, setting_name, value, expected_values:)+ result =+ SiteSetting::Update.call(+ guardian:,+ params: {+ settings: [{ setting_name:, value: serialize(value) }],+ },+ options: {+ expected_values:,+ },+ )+ return if result.success?++ if result["result.try.default"]&.exception.is_a?(SiteSetting::Update::Conflict)+ raise ToolError, I18n.t("mcp.errors.site_setting_conflict")+ end++ raise ToolError, update_error(result)+ rescue Discourse::InvalidParameters => error+ raise ToolError, error.message+ end++ def update_error(result)+ contract = result["result.contract.default"]+ return contract.errors.full_messages.to_sentence if contract&.failure?++ UPDATE_POLICIES.each do |policy_name|+ policy = result["result.policy.#{policy_name}"]+ return policy.reason if policy&.failure? && policy.reason.present?+ end+ result["result.step.save"]&.exception&.message.presence ||+ I18n.t("mcp.errors.site_setting_update_failed")+ end+ end++ class ListSiteSettings+ REQUIRED_SCOPES = [Scopes::SITE_SETTINGS_READ].freeze+ OUTPUT_SCHEMA =+ OutputSchema.object(site_settings: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)++ def self.call(arguments:, request_context:)+ SiteSettingSupport.ensure_admin!(request_context.guardian)+ offset = arguments.fetch("offset", 0)+ limit = arguments.fetch("limit", 100)+ requested_names = Array(arguments["names"]).to_set+ rows =+ SiteSettingSupport+ .settings(arguments)+ .select do |setting|+ requested_names.empty? || requested_names.include?(setting[:setting].to_s)+ end+ if arguments["overridden_only"]+ rows.select! { |setting| setting[:value].to_s != setting[:default].to_s }+ end+ page = rows.slice(offset, limit) || []+ has_more = offset + page.length < rows.length+ ToolHelpers.text_and_structured(+ site_settings: page.map { |setting| SiteSettingSupport.project(setting) },+ meta: {+ offset:,+ limit:,+ returned: page.length,+ total: rows.length,+ overridden_only: arguments.fetch("overridden_only", false),+ has_more:,+ next_offset: has_more ? offset + page.length : nil,+ },+ )+ end+ end++ class UpdateSiteSetting+ REQUIRED_SCOPES = [Scopes::SITE_SETTINGS_WRITE].freeze+ OUTPUT_SCHEMA =+ OutputSchema.object(+ updated: OutputSchema::BOOLEAN,+ setting: OutputSchema::STRING,+ operation: OutputSchema::STRING,+ before: OutputSchema::OBJECT,+ after: OutputSchema::OBJECT,+ verified: OutputSchema::BOOLEAN,+ )++ def self.call(arguments:, request_context:)+ guardian = request_context.guardian+ SiteSettingSupport.ensure_admin!(guardian)+ if arguments["confirm_change"] != true+ raise ToolError, I18n.t("mcp.errors.site_setting_change_confirmation_required")+ end+ setting_name = arguments.fetch("setting")+ setting = SiteSettingSupport.exact_setting(setting_name)+ raise ToolError, I18n.t("mcp.errors.site_setting_not_found") if setting.blank?+ if SiteSettingSupport.blocked?(setting)+ raise ToolError, I18n.t("mcp.errors.site_setting_sensitive")+ end+ if SiteSettingSupport.unsupported_type?(setting)+ raise ToolError, I18n.t("mcp.errors.site_setting_type_unsupported")+ end++ expected_values = SiteSettingSupport.ensure_dependencies!(setting)+ expected = SiteSettingSupport.normalize(arguments.fetch("expected_current_value"))+ if expected != SiteSettingSupport.normalize(setting[:value])+ raise ToolError, I18n.t("mcp.errors.site_setting_conflict")+ end+ if setting[:requires_confirmation].present? && !arguments["confirm_required_setting"]+ raise ToolError, I18n.t("mcp.errors.site_setting_confirmation_required")+ end++ operation = arguments.fetch("operation")+ value =+ case operation+ when "set"+ if !arguments.key?("value")+ raise ToolError, I18n.t("mcp.errors.site_setting_value_required")+ end+ arguments["value"]+ when "reset_to_default"+ if arguments.key?("value")+ raise ToolError, I18n.t("mcp.errors.site_setting_value_forbidden")+ end+ setting[:default]+ end+ if SiteSettingSupport.normalize(value) == SiteSettingSupport.normalize(setting[:value])+ raise ToolError, I18n.t("mcp.errors.site_setting_no_change")+ end++ before = SiteSettingSupport.project(setting)+ SiteSettingSupport.update!(+ guardian,+ setting_name,+ value,+ expected_values: expected_values.merge(setting_name => setting[:value]),+ )+ after_setting = SiteSettingSupport.exact_setting(setting_name)+ if after_setting.blank?+ raise ToolError, I18n.t("mcp.errors.site_setting_verification_failed")+ end+ if SiteSettingSupport.normalize(after_setting[:value]) ==+ SiteSettingSupport.normalize(setting[:value])+ raise ToolError, I18n.t("mcp.errors.site_setting_no_change")+ end++ ToolHelpers.text_and_structured(+ updated: true,+ setting: setting_name,+ operation:,+ before:,+ after: SiteSettingSupport.project(after_setting),+ verified: true,+ )+ end+ end+ end+enddiff --git a/spec/lib/discourse_mcp/staff_tools_spec.rb b/spec/lib/discourse_mcp/staff_tools_spec.rbnew file mode 100644index 00000000000..b0de4dfbd2c--- /dev/null+++ b/spec/lib/discourse_mcp/staff_tools_spec.rb@@ -0,0 +1,621 @@+# frozen_string_literal: true++describe DiscourseMcp::Tools do+ def request_context(user)+ instance_double(+ DiscourseMcp::RequestContext,+ user:,+ user_id: user.id,+ guardian: user.guardian,+ ).tap do |context|+ allow(context).to receive(:has_scopes?).and_return(true)+ allow(context).to receive(:ensure_scopes!)+ end+ end++ fab!(:user) { Fabricate(:user, refresh_auto_groups: true) }+ fab!(:moderator)+ fab!(:admin)++ describe "moderation reads" do+ fab!(:reviewable, :reviewable_flagged_post)++ it "requires access to the review queue" do+ tools = {+ DiscourseMcp::Tools::GetReviewQueueCount => {+ },+ DiscourseMcp::Tools::ListReviewables => {+ },+ DiscourseMcp::Tools::ListReviewableTopics => {+ },+ DiscourseMcp::Tools::GetReviewable => {+ "reviewable_id" => reviewable.id,+ },+ }++ tools.each do |tool, arguments|+ expect { tool.call(arguments:, request_context: request_context(user)) }.to raise_error(+ Discourse::InvalidAccess,+ )+ end+ end++ it "only returns reviewables visible to a category moderator" do+ SiteSetting.enable_category_group_moderation = true+ group = Fabricate(:group)+ group.add(user)+ allowed_category = Fabricate(:category)+ other_category = Fabricate(:category)+ Fabricate(:category_moderation_group, category: allowed_category, group:)+ allowed =+ Fabricate(+ :reviewable_flagged_post,+ category: allowed_category,+ topic: Fabricate(:topic, category: allowed_category),+ )+ Fabricate(+ :reviewable_flagged_post,+ category: other_category,+ topic: Fabricate(:topic, category: other_category),+ )++ result =+ DiscourseMcp::Tools::ListReviewables.call(+ arguments: {+ },+ request_context: request_context(user),+ ).fetch(:structuredContent)++ expect(result[:reviewables].pluck(:id)).to eq([allowed.id])+ expect(result[:meta]).to include(total: 1, returned: 1, has_more: false)+ end++ it "returns queue count, topic signals, and detail for staff" do+ context = request_context(moderator)++ count =+ DiscourseMcp::Tools::GetReviewQueueCount.call(+ arguments: {+ },+ request_context: context,+ ).fetch(:structuredContent)+ topics =+ DiscourseMcp::Tools::ListReviewableTopics.call(+ arguments: {+ },+ request_context: context,+ ).fetch(:structuredContent)+ detail =+ DiscourseMcp::Tools::GetReviewable.call(+ arguments: {+ "reviewable_id" => reviewable.id,+ },+ request_context: context,+ ).fetch(:structuredContent)++ expect(count).to include(count: 1, unit: "pending_reviewable_queue_items")+ expect(topics[:topics].pluck(:id)).to include(reviewable.topic_id)+ expect(detail[:reviewable]).to include(id: reviewable.id, version: reviewable.version)+ expect(detail[:actions]).to be_present+ end++ it "paginates topic signals before serializing them" do+ other_reviewable = Fabricate(:reviewable_flagged_post)++ first_page =+ DiscourseMcp::Tools::ListReviewableTopics.call(+ arguments: {+ "offset" => 0,+ "limit" => 1,+ },+ request_context: request_context(moderator),+ ).fetch(:structuredContent)+ second_page =+ DiscourseMcp::Tools::ListReviewableTopics.call(+ arguments: {+ "offset" => 1,+ "limit" => 1,+ },+ request_context: request_context(moderator),+ ).fetch(:structuredContent)++ expect(first_page[:topics].pluck(:id) + second_page[:topics].pluck(:id)).to contain_exactly(+ reviewable.topic_id,+ other_reviewable.topic_id,+ )+ expect(first_page[:meta]).to include(returned: 1, total: 2, has_more: true, next_offset: 1)+ expect(second_page[:meta]).to include(+ returned: 1,+ total: 2,+ has_more: false,+ next_offset: nil,+ )+ end+ end++ describe DiscourseMcp::Tools::GetUserModerationSummary do+ it "returns the native staff counters and rejects non-staff" do+ expect do+ described_class.call(+ arguments: {+ "username" => user.username,+ },+ request_context: request_context(user),+ )+ end.to raise_error(Discourse::InvalidAccess)++ result =+ described_class.call(+ arguments: {+ "username" => user.username,+ },+ request_context: request_context(moderator),+ ).fetch(:structuredContent)++ expect(result).to include(+ username: user.username,+ deleted_posts: user.number_of_deleted_posts,+ flags_received: user.number_of_flags,+ flags_given: user.number_of_flags_given,+ )+ end+ end++ describe DiscourseMcp::Tools::GetPostRevision do+ fab!(:post) { Fabricate(:post, user:) }++ before do+ SiteSetting.editing_grace_period = 0+ PostRevisor.new(post).revise!(user, raw: "revised post body")+ end++ it "uses review-queue and post-revision permissions" do+ expect do+ described_class.call(+ arguments: {+ "post_id" => post.id,+ },+ request_context: request_context(user),+ )+ end.to raise_error(Discourse::InvalidAccess)++ result =+ described_class.call(+ arguments: {+ "post_id" => post.id,+ "revision" => "latest",+ },+ request_context: request_context(moderator),+ ).fetch(:structuredContent)++ expect(result).to include(post_id: post.id, current_revision: 2)+ expect(result[:body_changes]).to be_present+ end++ it "returns revisions for deleted content visible to the reviewer" do+ post.trash!(moderator)++ deleted_post_result =+ described_class.call(+ arguments: {+ "post_id" => post.id,+ "revision" => "latest",+ },+ request_context: request_context(moderator),+ ).fetch(:structuredContent)++ post.recover!+ post.topic.trash!(moderator)+ deleted_topic_result =+ described_class.call(+ arguments: {+ "post_id" => post.id,+ "revision" => "latest",+ },+ request_context: request_context(moderator),+ ).fetch(:structuredContent)++ expect([deleted_post_result, deleted_topic_result]).to all(+ include(post_id: post.id, current_revision: 2),+ )+ end++ it "hides a deleted post outside a category moderator's scope" do+ SiteSetting.enable_category_group_moderation = true+ group = Fabricate(:group)+ group.add(user)+ moderated_category = Fabricate(:category)+ Fabricate(:category_moderation_group, category: moderated_category, group: group)+ Fabricate(:reviewable_flagged_post, category: moderated_category)+ post.trash!(moderator)++ expect do+ described_class.call(+ arguments: {+ "post_id" => post.id,+ "revision" => "latest",+ },+ request_context: request_context(user),+ )+ end.to raise_error(DiscourseMcp::ToolError, I18n.t("mcp.errors.post_not_found"))+ end+ end++ describe DiscourseMcp::Tools::PerformReviewableAction do+ fab!(:reviewable, :reviewable_queued_post)++ it "requires queue access, a current version, and a currently available action" do+ arguments = {+ "reviewable_id" => reviewable.id,+ "action_id" => "reject_post",+ "expected_version" => reviewable.version,+ "confirm" => true,+ }++ expect do+ described_class.call(arguments:, request_context: request_context(user))+ end.to raise_error(Discourse::InvalidAccess)++ expect do+ described_class.call(+ arguments: arguments.merge("expected_version" => reviewable.version + 1),+ request_context: request_context(moderator),+ )+ end.to raise_error(DiscourseMcp::ToolError, I18n.t("mcp.errors.reviewable_conflict"))++ result =+ described_class.call(arguments:, request_context: request_context(moderator)).fetch(+ :structuredContent,+ )++ expect(result).to include(success: true, reviewable_id: reviewable.id)+ expect(reviewable.reload).to be_rejected+ end++ it "fails closed for missing confirmation, claims, and extra fields" do+ base_arguments = {+ "reviewable_id" => reviewable.id,+ "action_id" => "reject_post",+ "expected_version" => reviewable.version,+ }+ context = request_context(moderator)++ expect do+ described_class.call(arguments: base_arguments, request_context: context)+ end.to raise_error(+ DiscourseMcp::ToolError,+ I18n.t("mcp.errors.reviewable_confirmation_required"),+ )++ expect do+ described_class.call(+ arguments:+ base_arguments.merge(+ "confirm" => true,+ "additional_fields" => {+ "unadvertised_field" => true,+ },+ ),+ request_context: context,+ )+ end.to raise_error(DiscourseMcp::ToolError, /unadvertised_field/)++ SiteSetting.reviewable_claiming = "required"+ expect do+ described_class.call(+ arguments: base_arguments.merge("confirm" => true),+ request_context: context,+ )+ end.to raise_error(DiscourseMcp::ToolError, I18n.t("reviewables.must_claim"))+ expect(reviewable.reload).to be_pending+ end+ end++ describe DiscourseMcp::Tools::ListSiteSettings do+ it "is admin-only and masks secret values" do+ expect do+ described_class.call(arguments: {}, request_context: request_context(moderator))+ end.to raise_error(Discourse::InvalidAccess)++ secret_name = "google_oauth2_client_secret"+ SiteSetting.google_oauth2_client_secret = "not returned by MCP"+ result =+ described_class.call(+ arguments: {+ "names" => [secret_name],+ },+ request_context: request_context(admin),+ ).fetch(:structuredContent)+ setting = result[:site_settings].sole++ expect(setting).to include(setting: secret_name, secret: true, value: nil, default: nil)+ expect(result.to_json).not_to include("not returned by MCP")+ end+ end++ describe DiscourseMcp::Tools::UpdateSiteSetting do+ it "is admin-only, checks the current value, and uses the audited update service" do+ arguments = {+ "setting" => "title",+ "operation" => "set",+ "value" => "A new MCP title",+ "expected_current_value" => SiteSetting.title,+ "confirm_change" => true,+ }++ expect do+ described_class.call(arguments:, request_context: request_context(moderator))+ end.to raise_error(Discourse::InvalidAccess)++ expect do+ described_class.call(+ arguments: arguments.merge("expected_current_value" => "stale title"),+ request_context: request_context(admin),+ )+ end.to raise_error(DiscourseMcp::ToolError, I18n.t("mcp.errors.site_setting_conflict"))++ expect do+ described_class.call(arguments:, request_context: request_context(admin))+ end.to change {+ UserHistory.where(action: UserHistory.actions[:change_site_setting], subject: "title").count+ }.by(1)++ expect(SiteSetting.title).to eq("A new MCP title")+ end++ it "returns the value normalized by the site-setting update service" do+ result =+ described_class.call(+ arguments: {+ "setting" => "max_image_size_kb",+ "operation" => "set",+ "value" => "8zf843",+ "expected_current_value" => SiteSetting.max_image_size_kb,+ "confirm_change" => true,+ },+ request_context: request_context(admin),+ ).fetch(:structuredContent)++ expect(SiteSetting.max_image_size_kb).to eq(8843)+ expect(result.dig(:after, :value)).to eq("8843")+ end++ it "rejects a concurrent update that uses a stale current value" do+ current_title = SiteSetting.title+ first_update_started = Queue.new+ second_update_started = Queue.new+ release_first_update = Queue.new+ call_count = 0+ call_count_mutex = Mutex.new++ allow(SiteSetting::Update).to receive(:call).and_wrap_original do |original, *args, **kwargs|+ current_call = call_count_mutex.synchronize { call_count += 1 }+ if current_call == 1+ first_update_started << true+ release_first_update.pop+ elsif current_call == 2+ second_update_started << true+ end+ original.call(*args, **kwargs)+ end++ outcomes = Queue.new+ update =+ lambda do |value|+ described_class.call(+ arguments: {+ "setting" => "title",+ "operation" => "set",+ "value" => value,+ "expected_current_value" => current_title,+ "confirm_change" => true,+ },+ request_context: request_context(admin),+ )+ outcomes << :success+ rescue => error+ outcomes << error+ end++ first_update = Thread.new { update.call("First concurrent title") }+ begin+ Timeout.timeout(5) { first_update_started.pop }+ second_update = Thread.new { update.call("Second concurrent title") }+ Timeout.timeout(5) { second_update_started.pop }+ ensure+ release_first_update << true+ first_update.join+ second_update&.join+ end++ results = 2.times.map { outcomes.pop }+ expect(results.grep(:success).length).to eq(1)+ expect(results.grep(DiscourseMcp::ToolError).map(&:message)).to eq(+ [I18n.t("mcp.errors.site_setting_conflict")],+ )+ expect(SiteSetting.title).to be_in(["First concurrent title", "Second concurrent title"])+ end++ it "rejects an MCP update when the admin UI changes the setting first" do+ current_title = SiteSetting.title+ mcp_update_started = Queue.new+ release_mcp_update = Queue.new++ allow(SiteSetting::Update).to receive(:call).and_wrap_original do |original, *args, **kwargs|+ if kwargs.dig(:options, :expected_values).present?+ mcp_update_started << true+ release_mcp_update.pop+ end+ original.call(*args, **kwargs)+ end++ outcome = Queue.new+ mcp_update =+ Thread.new do+ described_class.call(+ arguments: {+ "setting" => "title",+ "operation" => "set",+ "value" => "MCP title",+ "expected_current_value" => current_title,+ "confirm_change" => true,+ },+ request_context: request_context(admin),+ )+ outcome << :success+ rescue => error+ outcome << error+ end++ begin+ Timeout.timeout(5) { mcp_update_started.pop }+ admin_update =+ SiteSetting::Update.call(+ guardian: admin.guardian,+ params: {+ settings: [{ setting_name: "title", value: "Admin UI title" }],+ },+ )+ ensure+ release_mcp_update << true+ mcp_update.join+ end++ expect(admin_update).to be_success+ expect(outcome.pop).to be_a(DiscourseMcp::ToolError).and have_attributes(+ message: I18n.t("mcp.errors.site_setting_conflict"),+ )+ expect(SiteSetting.title).to eq("Admin UI title")+ end++ it "checks hidden site setting dependencies without exposing them" do+ SiteSetting.enable_local_logins_via_code = false++ expect do+ described_class.call(+ arguments: {+ "setting" => "enable_random_usernames",+ "operation" => "set",+ "value" => false,+ "expected_current_value" => SiteSetting.enable_random_usernames,+ "confirm_change" => true,+ },+ request_context: request_context(admin),+ )+ end.to raise_error(DiscourseMcp::ToolError, /enable_local_logins_via_code/)+ end++ it "updates a setting when its hidden dependencies are satisfied" do+ SiteSetting.enable_local_logins_via_code = true++ result =+ described_class.call(+ arguments: {+ "setting" => "enable_random_usernames",+ "operation" => "set",+ "value" => !SiteSetting.enable_random_usernames,+ "expected_current_value" => SiteSetting.enable_random_usernames,+ "confirm_change" => true,+ },+ request_context: request_context(admin),+ ).fetch(:structuredContent)++ expect(result).to include(updated: true, setting: "enable_random_usernames", verified: true)+ end++ it "refuses secret settings without exposing their value" do+ secret_name = "google_oauth2_client_secret"++ expect do+ described_class.call(+ arguments: {+ "setting" => secret_name,+ "operation" => "set",+ "value" => "replacement secret",+ "expected_current_value" => "unknown",+ "confirm_change" => true,+ },+ request_context: request_context(admin),+ )+ end.to raise_error(DiscourseMcp::ToolError, I18n.t("mcp.errors.site_setting_sensitive"))+ end++ it "refuses setting types that the global update service cannot safely change" do+ setting =+ DiscourseMcp::Tools::ListSiteSettings+ .call(+ arguments: {+ "names" => ["enable_welcome_banner"],+ },+ request_context: request_context(admin),+ )+ .dig(:structuredContent, :site_settings)+ .sole++ expect(setting).to include(themeable: true, editable_by_this_tool: false)+ expect do+ described_class.call(+ arguments: {+ "setting" => "enable_welcome_banner",+ "operation" => "set",+ "value" => "false",+ "expected_current_value" => setting[:value],+ "confirm_change" => true,+ },+ request_context: request_context(admin),+ )+ end.to raise_error(+ DiscourseMcp::ToolError,+ I18n.t("mcp.errors.site_setting_type_unsupported"),+ )+ end++ it "requires confirmation even when called outside the protocol dispatcher" do+ expect do+ described_class.call(+ arguments: {+ "setting" => "title",+ "operation" => "set",+ "value" => "Not applied",+ "expected_current_value" => SiteSetting.title,+ },+ request_context: request_context(admin),+ )+ end.to raise_error(+ DiscourseMcp::ToolError,+ I18n.t("mcp.errors.site_setting_change_confirmation_required"),+ )+ expect(SiteSetting.title).not_to eq("Not applied")+ end+ end++ it "registers the selected tools under separate read and write scopes" do+ expected = {+ "discourse_get_review_queue_count" => [DiscourseMcp::Scopes::MODERATION_READ],+ "discourse_list_reviewables" => [DiscourseMcp::Scopes::MODERATION_READ],+ "discourse_list_reviewable_topics" => [DiscourseMcp::Scopes::MODERATION_READ],+ "discourse_get_reviewable" => [DiscourseMcp::Scopes::MODERATION_READ],+ "discourse_get_user_moderation_summary" => [DiscourseMcp::Scopes::MODERATION_READ],+ "discourse_get_post_revision" => [DiscourseMcp::Scopes::MODERATION_READ],+ "discourse_perform_reviewable_action" => [DiscourseMcp::Scopes::MODERATION_WRITE],+ "discourse_list_site_settings" => [DiscourseMcp::Scopes::SITE_SETTINGS_READ],+ "discourse_update_site_setting" => [DiscourseMcp::Scopes::SITE_SETTINGS_WRITE],+ }++ actual =+ expected.keys.to_h do |identifier|+ [identifier, DiscourseMcp.registry.find(:tool, identifier)&.required_scopes]+ end++ expect(actual).to eq(expected)+ expect(+ DiscourseMcp.registry.find(:tool, "discourse_perform_reviewable_action").annotations,+ ).to include("destructiveHint" => true, "openWorldHint" => true)+ expect(+ DiscourseMcp.registry.find(:tool, "discourse_update_site_setting").annotations,+ ).to include("destructiveHint" => true, "idempotentHint" => true, "openWorldHint" => true)++ schemas = DiscourseMcp.registry.all.map(&:input_schema)+ expect(schemas.to_json).not_to include('\\\\A', '\\\\z')+ end+enddiff --git a/spec/requests/mcp_content_access_spec.rb b/spec/requests/mcp_content_access_spec.rbindex 90e3456b22b..827837e6f73 100644--- a/spec/requests/mcp_content_access_spec.rb+++ b/spec/requests/mcp_content_access_spec.rb@@ -61,6 +61,166 @@ describe "MCP content access" doexpect(response.body).not_to include(message.raw)end+ it "requires the dedicated moderation and site-setting scopes" do+ authorize+ operations = {+ "discourse_get_review_queue_count" => [{}, "mcp:moderation:read"],+ "discourse_list_reviewables" => [{}, "mcp:moderation:read"],+ "discourse_list_reviewable_topics" => [{}, "mcp:moderation:read"],+ "discourse_get_reviewable" => [{ reviewable_id: 1 }, "mcp:moderation:read"],+ "discourse_get_user_moderation_summary" => [+ { username: user.username },+ "mcp:moderation:read",+ ],+ "discourse_get_post_revision" => [{ post_id: 1 }, "mcp:moderation:read"],+ "discourse_perform_reviewable_action" => [+ { reviewable_id: 1, action_id: "reject", confirm: true },+ "mcp:moderation:write",+ ],+ "discourse_list_site_settings" => [{}, "mcp:site-settings:read"],+ "discourse_update_site_setting" => [+ {+ setting: "title",+ operation: "set",+ value: "Not applied",+ expected_current_value: SiteSetting.title,+ confirm_change: true,+ },+ "mcp:site-settings:write",+ ],+ }++ operations.each do |name, (arguments, scope)|+ call_tool(name, arguments)+ aggregate_failures(name) { expect_missing_scope(scope) }+ end++ expect(SiteSetting.title).not_to eq("Not applied")+ end++ it "does not let a moderation scope bypass Guardian" do+ authorize("mcp:moderation:read")++ call_tool("discourse_get_review_queue_count", {})++ expect(response.status).to eq(403)+ expect(response.parsed_body.dig("error", "message")).to eq("Not authorized")+ end++ it "does not let site-setting scopes bypass Guardian" do+ original_title = SiteSetting.title+ authorize("mcp:site-settings:read", "mcp:site-settings:write")++ call_tool("discourse_list_site_settings", {})+ expect(response.status).to eq(403)+ expect(response.parsed_body.dig("error", "message")).to eq("Not authorized")++ call_tool(+ "discourse_update_site_setting",+ {+ setting: "title",+ operation: "set",+ value: "Unauthorized title",+ expected_current_value: original_title,+ confirm_change: true,+ },+ )+ expect(response.status).to eq(403)+ expect(SiteSetting.title).to eq(original_title)+ end++ it "requires private-message read scope for private moderation content" do+ user.update!(moderator: true)+ Group.refresh_automatic_groups_for_user!(user)+ reviewable =+ Fabricate(+ :reviewable_flagged_post,+ topic: message.topic,+ target: message,+ target_created_by: message.user,+ )+ SiteSetting.editing_grace_period = 0+ PostRevisor.new(message).revise!(message.user, raw: "Revised private message")+ authorize("mcp:moderation:read")++ call_tool("discourse_get_review_queue_count", {})+ expect(response.parsed_body.dig("result", "structuredContent", "count")).to eq(0)++ call_tool("discourse_list_reviewables", {})+ expect(response.status).to eq(200)+ expect(response.parsed_body.dig("result", "structuredContent", "reviewables")).to eq([])++ call_tool("discourse_list_reviewable_topics", {})+ expect(response.parsed_body.dig("result", "structuredContent", "topics")).to eq([])++ call_tool("discourse_get_reviewable", { reviewable_id: reviewable.id })+ expect_missing_scope("mcp:private-messages:read")++ call_tool("discourse_get_post_revision", { post_id: message.id })+ expect_missing_scope("mcp:private-messages:read")+ expect(response.body).not_to include("Revised private message")++ authorize("mcp:moderation:read", "mcp:private-messages:read")+ call_tool("discourse_get_review_queue_count", {})+ expect(response.parsed_body.dig("result", "structuredContent", "count")).to eq(1)+ call_tool("discourse_get_reviewable", { reviewable_id: reviewable.id })+ expect(response.parsed_body.dig("result", "isError")).to eq(false)+ call_tool("discourse_get_post_revision", { post_id: message.id })+ expect(response.parsed_body.dig("result", "isError")).to eq(false)+ end++ it "omits private flag conversations without PM read scope while returning the public reviewable" do+ user.update!(moderator: true)+ Group.refresh_automatic_groups_for_user!(user)+ flag_reason = "private flag conversation 猫"+ result =+ PostActionCreator.notify_moderators(+ Fabricate(:user, refresh_auto_groups: true),+ Fabricate(:post),+ flag_reason,+ )+ authorize("mcp:moderation:read")++ call_tool("discourse_get_reviewable", { reviewable_id: result.reviewable.id })++ structured_content = response.parsed_body.dig("result", "structuredContent")+ expect(structured_content.dig("reviewable", "id")).to eq(result.reviewable.id)+ expect(structured_content["reviewable_conversations"]).to be_blank+ expect(structured_content["conversation_posts"]).to be_blank+ expect(response.body).not_to include(flag_reason)++ authorize("mcp:moderation:read", "mcp:private-messages:read")+ call_tool("discourse_get_reviewable", { reviewable_id: result.reviewable.id })++ expect(response.body).to include(flag_reason)+ end++ it "requires private-message write scope for private reviewable actions" do+ user.update!(moderator: true)+ Group.refresh_automatic_groups_for_user!(user)+ reviewable =+ Fabricate(+ :reviewable_flagged_post,+ topic: message.topic,+ target: message,+ target_created_by: message.user,+ )+ authorize("mcp:moderation:write", "mcp:private-messages:read")++ call_tool(+ "discourse_perform_reviewable_action",+ {+ reviewable_id: reviewable.id,+ action_id: "agree_and_keep",+ expected_version: reviewable.version,+ confirm: true,+ },+ )++ expect_missing_scope("mcp:private-messages:write")+ expect(reviewable.reload).to be_pending+ end+it "requires the read scope across generic private-message reads" doauthorize("mcp:private-messages:write")operations = {diff --git a/spec/services/site_setting/update_spec.rb b/spec/services/site_setting/update_spec.rbindex be340167d4a..e1cd3b0aa9f 100644--- a/spec/services/site_setting/update_spec.rb+++ b/spec/services/site_setting/update_spec.rb@@ -156,6 +156,17 @@ RSpec.describe SiteSetting::Update doendend+ context "when the expected value is stale" do+ let(:options) do+ { allow_changing_hidden:, expected_values: { setting_name => "a stale value" } }+ end++ it "does not update the setting" do+ expect { result }.to not_change { SiteSetting.title }+ expect(result["result.try.default"].exception).to be_a(SiteSetting::Update::Conflict)+ end+ end+context "when one setting is having invalid value" dolet(:settings) do[