Skip to content

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.rb
index 2f14746993f..3bf60409b19 100644
--- a/app/serializers/reviewable_score_serializer.rb
+++ b/app/serializers/reviewable_score_serializer.rb
@@ -56,6 +56,9 @@ class ReviewableScoreSerializer < ApplicationSerializer
def include_reviewable_conversation?
return false if object.meta_topic.blank?
+ if object.meta_topic.private_message? && @options[:include_private_conversations] == false
+ return false
+ end
scope&.can_see?(object.meta_topic) || object.notify_moderators_flag_message?
end
diff --git a/app/services/site_setting/update.rb b/app/services/site_setting/update.rb
index 900b8845fbd..42a910fca66 100644
--- a/app/services/site_setting/update.rb
+++ b/app/services/site_setting/update.rb
@@ -3,11 +3,15 @@
class SiteSetting::Update
include Service::Base
+ class Conflict < StandardError
+ end
+
Setting = Struct.new(:name, :value, :backfill, :change)
options do
attribute :allow_changing_hidden, :array, default: []
attribute :overridden_setting_names, default: -> { {} }
+ attribute :expected_values, default: -> { {} }
end
policy :current_user_is_admin
@@ -70,9 +74,13 @@ class SiteSetting::Update
policy :settings_are_configurable, class_name: SiteSetting::Policy::SettingsAreConfigurable
try do
- transaction do
- step :save
- step :backfill
+ lock do
+ step :ensure_expected_values
+
+ transaction do
+ step :save
+ step :backfill
+ end
end
end
@@ -82,6 +90,23 @@ class SiteSetting::Update
guardian.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.yml
index 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.rb
index 054124c36ff..8f6b9f6ecca 100644
--- a/lib/discourse_mcp.rb
+++ b/lib/discourse_mcp.rb
@@ -10,6 +10,10 @@ module DiscourseMcp
DRAFTS_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"
end
PROTOCOL_VERSION = "2026-07-28"
diff --git a/lib/discourse_mcp/core_primitives.rb b/lib/discourse_mcp/core_primitives.rb
index df3c82369ca..3685d093d1d 100644
--- a/lib/discourse_mcp/core_primitives.rb
+++ b/lib/discourse_mcp/core_primitives.rb
@@ -65,6 +65,8 @@ module DiscourseMcp
registry = DiscourseMcp.registry
register_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 DiscourseMcp
implementation: 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 DiscourseMcp
implementation: 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.rb
index 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.rb
new file mode 100644
index 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
+end
diff --git a/lib/discourse_mcp/tools/site_settings.rb b/lib/discourse_mcp/tools/site_settings.rb
new file mode 100644
index 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
+end
diff --git a/spec/lib/discourse_mcp/staff_tools_spec.rb b/spec/lib/discourse_mcp/staff_tools_spec.rb
new file mode 100644
index 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
+end
diff --git a/spec/requests/mcp_content_access_spec.rb b/spec/requests/mcp_content_access_spec.rb
index 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" do
expect(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" do
authorize("mcp:private-messages:write")
operations = {
diff --git a/spec/services/site_setting/update_spec.rb b/spec/services/site_setting/update_spec.rb
index 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 do
end
end
+ 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" do
let(:settings) do
[