Skip to content

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

FEATURE: Add group read tools to the MCP server (#44136)

Natalie Taya27a41cf6d6c
diff --git a/app/controllers/groups_controller.rb b/app/controllers/groups_controller.rb
index f86df6c2bc0..ed2c4437c68 100644
--- a/app/controllers/groups_controller.rb
+++ b/app/controllers/groups_controller.rb
@@ -23,100 +23,41 @@ class GroupsController < ApplicationController
skip_before_action :check_xhr, only: [:show]
after_action :add_noindex_header
- TYPE_FILTERS = {
- my:
- Proc.new do |groups, user|
- raise Discourse::NotFound unless user
- Group.member_of(groups, user)
- end,
- owner:
- Proc.new do |groups, user|
- raise Discourse::NotFound unless user
- Group.owner_of(groups, user)
- end,
- public: Proc.new { |groups| groups.where(public_admission: true, automatic: false) },
- close: Proc.new { |groups| groups.where(public_admission: false, automatic: false) },
- automatic: Proc.new { |groups| groups.where(automatic: true) },
- non_automatic: Proc.new { |groups| groups.where(automatic: false) },
- }
+ TYPE_FILTERS = GroupDirectoryQuery::TYPE_FILTERS
ADD_MEMBERS_LIMIT = 1000
def index
- unless SiteSetting.enable_group_directory? || current_user&.staff?
- raise Discourse::InvalidAccess.new(:enable_group_directory)
- end
-
- requested_order = %w[name user_count].delete(params[:order])
- dir = params[:asc].to_s == "true" ? "ASC" : "DESC"
- groups = Group.visible_groups(current_user)
- type_filters = TYPE_FILTERS.keys
-
- if (username = params[:username]).present?
- raise Discourse::NotFound unless user = User.find_by_username(username)
- groups = TYPE_FILTERS[:my].call(groups.members_visible_groups(current_user), user)
- type_filters = type_filters - %i[my owner]
- end
-
- if (filter = params[:filter]).present?
- groups = Group.search_groups(filter, groups: groups)
- end
-
- if !guardian.is_staff?
- # hide automatic groups from all non stuff to de-clutter page
- groups =
- groups.where("groups.automatic IS FALSE OR groups.id = ?", Group::AUTO_GROUPS[:moderators])
- type_filters.delete(:automatic)
- end
-
- if Group.preloaded_custom_field_names.present?
- Group.preload_custom_fields(groups, Group.preloaded_custom_field_names)
- end
-
- if type = params[:type]&.to_sym
- raise Discourse::InvalidParameters.new(:type) unless callback = TYPE_FILTERS[type]
- groups = callback.call(groups, current_user)
- end
-
- if current_user
- group_users = GroupUser.where(group: groups, user: current_user)
- user_group_ids = group_users.pluck(:group_id)
- owner_group_ids = group_users.where(owner: true).pluck(:group_id)
- else
- type_filters = type_filters - %i[my owner]
- end
-
- groups = DiscoursePluginRegistry.apply_modifier(:groups_index_query, groups, self)
-
- type_filters.delete(:non_automatic)
-
- order = group_directory_order(groups, requested_order)
- groups = apply_group_directory_order(groups, order, dir)
-
- # count the total before doing pagination
- total = groups.count
-
page = fetch_int_from_params(:page, default: 0)
page_size = MobileDetection.mobile_device?(request.user_agent) ? 15 : 36
- groups = groups.offset(page * page_size).limit(page_size)
+ filter = params[:filter]
+ type = params[:type]
+ result =
+ GroupDirectoryQuery.new(user: current_user, guardian:, modifier_context: self).call(
+ username: params[:username],
+ filter:,
+ type:,
+ order: params[:order],
+ ascending: params[:asc].to_s == "true",
+ page:,
+ limit: page_size,
+ )
+ user_group_ids = result.memberships.keys
+ owner_group_ids =
+ result.memberships.filter_map { |group_id, membership| group_id if membership.owner? }
render_json_dump(
groups:
- serialize_data(
- groups,
- BasicGroupSerializer,
- user_group_ids: user_group_ids || [],
- owner_group_ids: owner_group_ids || [],
- ),
+ serialize_data(result.groups, BasicGroupSerializer, user_group_ids:, owner_group_ids:),
extras: {
- type_filters: type_filters,
+ type_filters: result.type_filters,
},
- total_rows_groups: total,
+ total_rows_groups: result.total,
load_more_groups:
groups_path(
page: page + 1,
type: type,
- order: order,
- asc: order ? params[:asc] : nil,
+ order: result.order,
+ asc: result.order ? params[:asc] : nil,
filter: filter,
),
)
@@ -794,28 +735,6 @@ class GroupsController < ApplicationController
private
- def group_directory_order(groups, requested_order)
- return requested_order if requested_order != "user_count"
-
- member_visible_group_ids =
- Group.members_visible_groups(current_user).unscope(:order).select(:id)
-
- requested_order if !groups.unscope(:order).where.not(id: member_visible_group_ids).exists?
- end
-
- def apply_group_directory_order(groups, order, dir)
- return groups if order.blank?
-
- sort =
- if order == "user_count"
- "groups.user_count #{dir}, groups.name ASC"
- else
- "groups.name #{dir}"
- end
-
- groups.reorder(sort)
- end
-
def add_users_to_group(group, users, notify = false)
user_ids = users.map(&:id)
added_user_ids = GroupManager.new(group).add(user_ids)
diff --git a/app/models/group.rb b/app/models/group.rb
index 89223e8a4c0..b68b5da0eb2 100644
--- a/app/models/group.rb
+++ b/app/models/group.rb
@@ -493,9 +493,22 @@ class Group < ActiveRecord::Base
result = guardian.filter_allowed_categories(result)
result = guardian.filter_hidden_posts(result)
- result = result.where("posts.id < ?", opts[:before_post_id].to_i) if opts[:before_post_id]
+ if opts[:before_post_id]
+ before_post_id = opts[:before_post_id].to_i
+ before_post_created_at = result.where(posts: { id: before_post_id }).pick("posts.created_at")
+ result =
+ if before_post_created_at
+ result.where(
+ "(posts.created_at, posts.id) < (:created_at, :id)",
+ created_at: before_post_created_at,
+ id: before_post_id,
+ )
+ else
+ result.none
+ end
+ end
result = result.where("posts.created_at < ?", opts[:before].to_datetime) if opts[:before]
- result.order("posts.created_at desc")
+ result.order("posts.created_at DESC, posts.id DESC")
end
def self.trust_group_ids
diff --git a/config/locales/server.en.yml b/config/locales/server.en.yml
index d3dcf60d13a..94c4c2eff5d 100644
--- a/config/locales/server.en.yml
+++ b/config/locales/server.en.yml
@@ -23,6 +23,7 @@ en:
draft_sequence_conflict: "Draft sequence conflict"
draft_too_long: "Draft is too long"
group_not_found: "Group not found"
+ group_post_single_cursor: "Provide either before_post_id or before, not both"
invalid_date: "Invalid date"
invalid_directory_period: "Invalid directory period"
invalid_reply_mode: "Invalid reply mode"
diff --git a/lib/discourse_mcp.rb b/lib/discourse_mcp.rb
index 2c0429ed196..0b5b398eee4 100644
--- a/lib/discourse_mcp.rb
+++ b/lib/discourse_mcp.rb
@@ -16,6 +16,7 @@ module DiscourseMcp
SITE_SETTINGS_WRITE = "mcp:site-settings:write"
THEMES_READ = "mcp:themes:read"
THEMES_WRITE = "mcp:themes:write"
+ GROUPS_READ = "mcp:groups:read"
end
PROTOCOL_VERSION = "2026-07-28"
diff --git a/lib/discourse_mcp/core_primitives.rb b/lib/discourse_mcp/core_primitives.rb
index 1c051187d5d..4d2d7d94b06 100644
--- a/lib/discourse_mcp/core_primitives.rb
+++ b/lib/discourse_mcp/core_primitives.rb
@@ -68,6 +68,7 @@ module DiscourseMcp
register_moderation_tools(registry)
register_site_setting_tools(registry)
register_theme_tools(registry)
+ register_group_tools(registry)
register_resources(registry)
register_prompts(registry)
end
@@ -1645,6 +1646,153 @@ module DiscourseMcp
)
end
+ def register_group_tools(registry)
+ group_name = { type: "string", minLength: 1, maxLength: 100 }
+ pagination = {
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: 100,
+ },
+ offset: {
+ type: "integer",
+ minimum: 0,
+ },
+ }
+ register_tool(
+ registry,
+ "discourse_list_groups",
+ title: "List groups",
+ description: "Lists groups visible to the authenticated user.",
+ implementation: Tools::ListGroups,
+ input_schema:
+ object_schema(
+ {
+ page: {
+ type: "integer",
+ minimum: 0,
+ },
+ limit: pagination[:limit],
+ order: {
+ type: "string",
+ enum: %w[name user_count],
+ },
+ ascending: {
+ type: "boolean",
+ },
+ filter: {
+ type: "string",
+ minLength: 1,
+ maxLength: 100,
+ },
+ username: {
+ type: "string",
+ minLength: 1,
+ maxLength: 60,
+ },
+ type: {
+ type: "string",
+ enum: %w[my owner public close automatic non_automatic],
+ },
+ },
+ ),
+ annotations: READ_ONLY,
+ )
+ register_tool(
+ registry,
+ "discourse_get_group",
+ title: "Get group",
+ description: "Gets safe details and caller capabilities for one visible group.",
+ implementation: Tools::GetGroup,
+ input_schema: object_schema({ id: { type: "integer", minimum: 1 }, name: group_name }),
+ annotations: READ_ONLY,
+ )
+ register_tool(
+ registry,
+ "discourse_list_group_members",
+ title: "List group members",
+ description: "Lists members and owners when the authenticated user may see them.",
+ implementation: Tools::ListGroupMembers,
+ input_schema:
+ object_schema(
+ {
+ name: group_name,
+ **pagination,
+ filter: {
+ type: "string",
+ minLength: 1,
+ maxLength: 100,
+ },
+ order: {
+ type: "string",
+ enum: %w[username last_posted_at last_seen_at added_at],
+ },
+ ascending: {
+ type: "boolean",
+ },
+ },
+ required: %w[name],
+ ),
+ annotations: READ_ONLY,
+ )
+ register_tool(
+ registry,
+ "discourse_list_group_membership_requests",
+ title: "List group membership requests",
+ description: "Lists pending requests for a group the authenticated user may manage.",
+ implementation: Tools::ListGroupMembershipRequests,
+ input_schema:
+ object_schema(
+ {
+ name: group_name,
+ **pagination,
+ filter: {
+ type: "string",
+ minLength: 1,
+ maxLength: 100,
+ },
+ ascending: {
+ type: "boolean",
+ },
+ },
+ required: %w[name],
+ ),
+ annotations: READ_ONLY,
+ )
+ register_tool(
+ registry,
+ "discourse_list_group_posts",
+ title: "List group posts",
+ description: "Lists visible public-topic posts authored by members of a visible group.",
+ implementation: Tools::ListGroupPosts,
+ input_schema:
+ object_schema(
+ {
+ name: group_name,
+ before_post_id: {
+ type: "integer",
+ minimum: 1,
+ },
+ before: {
+ type: "string",
+ format: "date-time",
+ },
+ category_id: {
+ type: "integer",
+ minimum: 1,
+ },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: 20,
+ },
+ },
+ required: %w[name],
+ ),
+ annotations: READ_ONLY,
+ )
+ end
+
def register_resources(registry)
register_resource_template(
registry,
diff --git a/lib/discourse_mcp/core_tools.rb b/lib/discourse_mcp/core_tools.rb
index 6f7d1116d56..c6c713f433f 100644
--- a/lib/discourse_mcp/core_tools.rb
+++ b/lib/discourse_mcp/core_tools.rb
@@ -14,3 +14,4 @@ require "discourse_mcp/tools/private_messages"
require "discourse_mcp/tools/moderation"
require "discourse_mcp/tools/site_settings"
require "discourse_mcp/tools/themes"
+require "discourse_mcp/tools/groups"
diff --git a/lib/discourse_mcp/tools/groups.rb b/lib/discourse_mcp/tools/groups.rb
new file mode 100644
index 00000000000..22512952399
--- /dev/null
+++ b/lib/discourse_mcp/tools/groups.rb
@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require "group_directory_query"
+
+module DiscourseMcp
+ module Tools
+ module GroupSupport
+ MEMBERSHIP_NOT_LOADED = Object.new.freeze
+ SAFE_DETAIL_FIELDS = %i[
+ id
+ automatic
+ name
+ display_name
+ user_count
+ mentionable_level
+ messageable_level
+ visibility_level
+ primary_group
+ title
+ grant_trust_level
+ has_messages
+ flair_url
+ flair_bg_color
+ flair_color
+ bio_raw
+ bio_cooked
+ bio_excerpt
+ public_admission
+ public_exit
+ allow_membership_requests
+ full_name
+ default_notification_level
+ membership_request_template
+ is_group_user
+ is_group_owner
+ is_group_owner_display
+ members_visibility_level
+ can_see_members
+ can_admin_group
+ can_edit_group
+ publish_read_state
+ automatic_membership_email_domains
+ watching_category_ids
+ tracking_category_ids
+ watching_first_post_category_ids
+ regular_category_ids
+ muted_category_ids
+ watching_tags
+ watching_first_post_tags
+ tracking_tags
+ regular_tags
+ muted_tags
+ mentionable
+ messageable
+ flair_icon
+ flair_type
+ message_count
+ allow_unknown_sender_topic_replies
+ associated_group_ids
+ ].freeze
+
+ module_function
+
+ def find_visible!(arguments, guardian)
+ id = arguments["id"]
+ name = arguments["name"].to_s.strip.presence
+ raise ToolError, I18n.t("mcp.errors.group_not_found") if id.present? == name.present?
+
+ group =
+ if id
+ Group.visible_groups(guardian.user).find_by(id:)
+ else
+ Group.visible_groups(guardian.user).find_by("LOWER(groups.name) = ?", name.downcase)
+ end
+ group or raise ToolError, I18n.t("mcp.errors.group_not_found")
+ end
+
+ def group_json(
+ group,
+ guardian,
+ membership: MEMBERSHIP_NOT_LOADED,
+ can_see_members: MEMBERSHIP_NOT_LOADED
+ )
+ if membership.equal?(MEMBERSHIP_NOT_LOADED)
+ membership = group.group_users.find_by(user: guardian.user) if guardian.authenticated?
+ end
+ if can_see_members.equal?(MEMBERSHIP_NOT_LOADED)
+ can_see_members = guardian.can_see_group_members?(group)
+ end
+
+ can_admin_group = guardian.can_admin_group?(group)
+ {
+ id: group.id,
+ name: group.name,
+ full_name: group.full_name,
+ title: group.title,
+ automatic: group.automatic,
+ user_count: can_see_members ? group.user_count : nil,
+ visibility_level: group.visibility_level,
+ members_visibility_level: group.members_visibility_level,
+ mentionable_level: group.mentionable_level,
+ messageable_level: group.messageable_level,
+ public_admission: group.public_admission,
+ public_exit: group.public_exit,
+ allow_membership_requests: group.allow_membership_requests,
+ bio_excerpt: group.bio_cooked.present? ? PrettyText.excerpt(group.bio_cooked, 200) : nil,
+ is_group_user: membership.present?,
+ is_group_owner: membership&.owner? || false,
+ can_see_members:,
+ can_edit_group: guardian.can_edit_group?(group, group_user: membership),
+ can_admin_group:,
+ }
+ end
+
+ def group_detail_json(group, guardian)
+ GroupShowSerializer
+ .new(group, scope: guardian, root: false)
+ .as_json
+ .slice(*SAFE_DETAIL_FIELDS)
+ end
+
+ def filter_users(users, filter, guardian)
+ return users if filter.blank?
+
+ filter = filter.split(",") if filter.include?(",")
+ if guardian.is_admin?
+ users.filter_by_username_or_email(filter)
+ else
+ users.filter_by_username(filter)
+ end
+ end
+ end
+
+ class ListGroups
+ REQUIRED_SCOPES = [Scopes::GROUPS_READ].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(groups: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)
+
+ def self.call(arguments:, request_context:)
+ guardian = request_context.guardian
+ page = arguments.fetch("page", 0)
+ limit = arguments.fetch("limit", 36)
+ result =
+ GroupDirectoryQuery.new(
+ user: request_context.user,
+ guardian:,
+ modifier_context: request_context,
+ ).call(
+ username: arguments["username"],
+ filter: arguments["filter"],
+ type: arguments["type"],
+ order: arguments["order"],
+ ascending: arguments.fetch("ascending", true),
+ page:,
+ limit:,
+ )
+ groups = result.groups
+ member_visible_group_ids =
+ Group
+ .where(id: groups.map(&:id))
+ .members_visible_groups(
+ guardian.user,
+ nil,
+ include_pseudogroups: true,
+ include_everyone: true,
+ )
+ .pluck(:id)
+ .to_set
+
+ ToolHelpers.text_and_structured(
+ groups:
+ groups.map do |group|
+ GroupSupport.group_json(
+ group,
+ guardian,
+ membership: result.memberships[group.id],
+ can_see_members: member_visible_group_ids.include?(group.id),
+ )
+ end,
+ meta: {
+ page:,
+ limit:,
+ total: result.total,
+ has_more: (page + 1) * limit < result.total,
+ },
+ )
+ rescue Discourse::NotFound
+ raise ToolError, I18n.t("mcp.errors.group_not_found")
+ end
+ end
+
+ class GetGroup
+ REQUIRED_SCOPES = [Scopes::GROUPS_READ].freeze
+ OUTPUT_SCHEMA = OutputSchema.object(group: OutputSchema::OBJECT)
+
+ def self.call(arguments:, request_context:)
+ group = GroupSupport.find_visible!(arguments, request_context.guardian)
+ ToolHelpers.text_and_structured(
+ group: GroupSupport.group_detail_json(group, request_context.guardian),
+ )
+ end
+ end
+
+ class ListGroupMembers
+ REQUIRED_SCOPES = [Scopes::GROUPS_READ].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(members: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)
+
+ def self.call(arguments:, request_context:)
+ guardian = request_context.guardian
+ group = GroupSupport.find_visible!({ "name" => arguments.fetch("name") }, guardian)
+ guardian.ensure_can_see_group_members!(group)
+
+ users = group.listed_users.includes(:user_option, :user_stat)
+ users = GroupSupport.filter_users(users, arguments["filter"], guardian)
+ direction = arguments.fetch("ascending", true) ? "ASC" : "DESC"
+ order =
+ case arguments.fetch("order", "username")
+ when "last_posted_at", "last_seen_at"
+ "users.#{arguments.fetch("order")} #{direction} NULLS LAST"
+ when "added_at"
+ "group_users.created_at #{direction}"
+ else
+ "users.username_lower #{direction}"
+ end
+ users = users.reorder(Arel.sql(order), username_lower: direction.downcase.to_sym)
+ total = users.count
+ offset = arguments.fetch("offset", 0)
+ limit = arguments.fetch("limit", 50)
+ users = users.offset(offset).limit(limit).to_a
+ memberships = group.group_users.where(user: users).index_by(&:user_id)
+
+ ToolHelpers.text_and_structured(
+ members:
+ users.map do |member|
+ membership = memberships.fetch(member.id)
+ member_json = {
+ id: member.id,
+ username: member.username,
+ name: SiteSetting.enable_names? ? member.name : nil,
+ owner: membership.owner,
+ added_at: membership.created_at.iso8601,
+ }
+ if guardian.can_see_profile?(member)
+ member_json[:last_posted_at] = member.last_posted_at&.iso8601
+ member_json[:last_seen_at] = member.last_seen_at&.iso8601
+ end
+ member_json
+ end,
+ meta: {
+ offset:,
+ limit:,
+ total:,
+ has_more: offset + limit < total,
+ },
+ )
+ end
+ end
+
+ class ListGroupMembershipRequests
+ REQUIRED_SCOPES = [Scopes::GROUPS_READ].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(requests: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)
+
+ def self.call(arguments:, request_context:)
+ guardian = request_context.guardian
+ group = GroupSupport.find_visible!({ "name" => arguments.fetch("name") }, guardian)
+ guardian.ensure_can_edit!(group)
+
+ requests = group.group_requests.includes(:user)
+ if arguments["filter"].present?
+ matching_users =
+ GroupSupport.filter_users(group.requesters, arguments["filter"], guardian)
+ requests = requests.where(user_id: matching_users.select("users.id"))
+ end
+ direction = arguments.fetch("ascending", true) ? :asc : :desc
+ requests = requests.order(created_at: direction, id: direction)
+ total = requests.count
+ offset = arguments.fetch("offset", 0)
+ limit = arguments.fetch("limit", 50)
+ requests = requests.offset(offset).limit(limit)
+
+ ToolHelpers.text_and_structured(
+ requests:
+ requests.map do |request|
+ {
+ user_id: request.user_id,
+ username: request.user.username,
+ name: SiteSetting.enable_names? ? request.user.name : nil,
+ reason: request.reason,
+ requested_at: request.created_at.iso8601,
+ }
+ end,
+ meta: {
+ offset:,
+ limit:,
+ total:,
+ has_more: offset + limit < total,
+ },
+ )
+ end
+ end
+
+ class ListGroupPosts
+ REQUIRED_SCOPES = [Scopes::GROUPS_READ].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(posts: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)
+
+ def self.call(arguments:, request_context:)
+ if arguments["before_post_id"].present? && arguments["before"].present?
+ raise ToolError, I18n.t("mcp.errors.group_post_single_cursor")
+ end
+
+ guardian = request_context.guardian
+ group = GroupSupport.find_visible!({ "name" => arguments.fetch("name") }, guardian)
+ guardian.ensure_can_see_group_members!(group)
+ limit = arguments.fetch("limit", 20)
+ filters = {
+ before_post_id: arguments["before_post_id"],
+ before: arguments["before"],
+ category_id: arguments["category_id"],
+ }.compact
+ posts = group.posts_for(guardian, filters).limit(limit + 1).to_a
+ has_more = posts.length > limit
+ posts = posts.first(limit)
+
+ ToolHelpers.text_and_structured(
+ posts:
+ posts.map do |post|
+ ToolHelpers.evidence_post_json(
+ post,
+ excerpt: ToolHelpers.post_excerpt(post, guardian),
+ )
+ end,
+ meta: {
+ limit:,
+ has_more:,
+ next_before_post_id: has_more ? posts.last&.id : nil,
+ },
+ )
+ end
+ end
+ end
+end
diff --git a/lib/group_directory_query.rb b/lib/group_directory_query.rb
new file mode 100644
index 00000000000..d5c51c77135
--- /dev/null
+++ b/lib/group_directory_query.rb
@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+class GroupDirectoryQuery
+ TYPE_FILTERS = {
+ my:
+ Proc.new do |groups, user|
+ raise Discourse::NotFound unless user
+ Group.member_of(groups, user)
+ end,
+ owner:
+ Proc.new do |groups, user|
+ raise Discourse::NotFound unless user
+ Group.owner_of(groups, user)
+ end,
+ public: Proc.new { |groups| groups.where(public_admission: true, automatic: false) },
+ close: Proc.new { |groups| groups.where(public_admission: false, automatic: false) },
+ automatic: Proc.new { |groups| groups.where(automatic: true) },
+ non_automatic: Proc.new { |groups| groups.where(automatic: false) },
+ }.freeze
+
+ Result = Data.define(:groups, :total, :type_filters, :order, :memberships)
+
+ def initialize(user:, guardian:, modifier_context:)
+ @user = user
+ @guardian = guardian
+ @modifier_context = modifier_context
+ end
+
+ def call(username: nil, filter: nil, type: nil, order: nil, ascending: false, page: 0, limit: 36)
+ unless SiteSetting.enable_group_directory? || user&.staff?
+ raise Discourse::InvalidAccess.new(:enable_group_directory)
+ end
+
+ groups = Group.visible_groups(user)
+ type_filters = TYPE_FILTERS.keys
+
+ if username.present?
+ target_user = User.find_by_username(username)
+ raise Discourse::NotFound if target_user.blank?
+
+ groups = TYPE_FILTERS[:my].call(groups.members_visible_groups(user), target_user)
+ type_filters -= %i[my owner]
+ end
+
+ groups = Group.search_groups(filter, groups:) if filter.present?
+
+ if !guardian.is_staff?
+ groups =
+ groups.where("groups.automatic IS FALSE OR groups.id = ?", Group::AUTO_GROUPS[:moderators])
+ type_filters.delete(:automatic)
+ end
+
+ if type.present?
+ type = type.to_sym
+ callback = TYPE_FILTERS[type]
+ raise Discourse::InvalidParameters.new(:type) if callback.blank?
+
+ groups = callback.call(groups, user)
+ end
+
+ groups = DiscoursePluginRegistry.apply_modifier(:groups_index_query, groups, modifier_context)
+ type_filters.delete(:non_automatic)
+ type_filters -= %i[my owner] if user.blank?
+
+ order = allowed_order(groups, order)
+ groups = apply_order(groups, order, ascending)
+ total = groups.count
+ groups = groups.offset(page * limit).limit(limit).to_a
+ if Group.preloaded_custom_field_names.present?
+ Group.preload_custom_fields(groups, Group.preloaded_custom_field_names)
+ end
+ memberships = user ? GroupUser.where(group: groups, user:).index_by(&:group_id) : {}
+
+ Result.new(groups:, total:, type_filters:, order:, memberships:)
+ end
+
+ private
+
+ attr_reader :guardian, :modifier_context, :user
+
+ def allowed_order(groups, requested_order)
+ requested_order = %w[name user_count].delete(requested_order)
+ return requested_order if requested_order != "user_count"
+
+ member_visible_group_ids = Group.members_visible_groups(user).unscope(:order).select(:id)
+ requested_order if !groups.unscope(:order).where.not(id: member_visible_group_ids).exists?
+ end
+
+ def apply_order(groups, order, ascending)
+ return groups if order.blank?
+
+ direction = ascending ? "ASC" : "DESC"
+ sort =
+ if order == "user_count"
+ "groups.user_count #{direction}, groups.name ASC"
+ else
+ "groups.name #{direction}"
+ end
+ groups.reorder(sort)
+ end
+end
diff --git a/lib/guardian/group_guardian.rb b/lib/guardian/group_guardian.rb
index fbd2a793eaf..7bfb0b7b7da 100644
--- a/lib/guardian/group_guardian.rb
+++ b/lib/guardian/group_guardian.rb
@@ -2,6 +2,8 @@
#mixin for all guardian methods dealing with group permissions
module GroupGuardian
+ GROUP_USER_NOT_PRELOADED = Object.new.freeze
+
# Creating Method
def can_create_group?
is_admin? || (SiteSetting.moderators_manage_groups && is_moderator?)
@@ -10,9 +12,12 @@ module GroupGuardian
# Edit authority for groups means membership changes only.
# Automatic groups are not represented in the GROUP_USERS
# table and thus do not allow membership changes.
- def can_edit_group?(group)
- !group.automatic &&
- (can_admin_group?(group) || group.users.where("group_users.owner").include?(user))
+ def can_edit_group?(group, group_user: GROUP_USER_NOT_PRELOADED)
+ return false if group.automatic
+ return true if can_admin_group?(group)
+
+ group_user = group.group_users.find_by(user:) if group_user.equal?(GROUP_USER_NOT_PRELOADED)
+ group_user&.owner? || false
end
def can_admin_group?(group)
diff --git a/spec/lib/guardian_spec.rb b/spec/lib/guardian_spec.rb
index a10c9752992..d4c28a62da3 100644
--- a/spec/lib/guardian_spec.rb
+++ b/spec/lib/guardian_spec.rb
@@ -2945,6 +2945,27 @@ RSpec.describe Guardian do
end
end
+ describe "#can_edit_group?" do
+ it "accepts a preloaded group membership" do
+ group.add(member)
+ group.add_owner(owner)
+
+ expect(
+ Guardian.new(owner).can_edit_group?(
+ group,
+ group_user: group.group_users.find_by(user: owner),
+ ),
+ ).to eq(true)
+ expect(
+ Guardian.new(member).can_edit_group?(
+ group,
+ group_user: group.group_users.find_by(user: member),
+ ),
+ ).to eq(false)
+ expect(Guardian.new(another_user).can_edit_group?(group, group_user: nil)).to eq(false)
+ end
+ end
+
describe "#can_see_group?" do
it "Correctly handles owner visible groups" do
group = Fabricate(:group, visibility_level: Group.visibility_levels[:owners])
diff --git a/spec/requests/mcp_groups_spec.rb b/spec/requests/mcp_groups_spec.rb
new file mode 100644
index 00000000000..a41215c3b76
--- /dev/null
+++ b/spec/requests/mcp_groups_spec.rb
@@ -0,0 +1,515 @@
+# frozen_string_literal: true
+
+describe "MCP group tools" do
+ fab!(:user) { Fabricate(:user, refresh_auto_groups: true) }
+ fab!(:scope_group, :group)
+
+ before do
+ SiteSetting.mcp_server_enabled = true
+ scope_group.add(user)
+ end
+
+ def authorize(*extra_scopes, auth_user: user)
+ scope_group.add(auth_user)
+ scopes = [DiscourseMcp::INITIAL_SCOPE, *extra_scopes]
+ scopes.each { |scope| McpGroupScope.find_or_create_by!(group: scope_group, scope:) }
+ client =
+ McpOauthClient.create!(
+ client_id: SecureRandom.hex,
+ name: "Group tool test client",
+ registration_type: "pre_registered",
+ trust_state: "approved",
+ redirect_uris: ["http://127.0.0.1/callback"],
+ )
+ authorization =
+ DiscourseMcp::OAuth::AuthorizationGrant.create!(
+ user: auth_user,
+ client:,
+ redirect_uri: client.redirect_uris.first,
+ requested_scopes: scopes,
+ )
+ @token = McpOauthAccessToken.issue!(authorization:)
+ end
+
+ def call_tool(name, arguments = {})
+ McpPrimitive.find_or_create_by!(kind: "tool", identifier: name) do |primitive|
+ primitive.enabled = true
+ end
+ post "/mcp",
+ params: {
+ jsonrpc: "2.0",
+ id: 1,
+ method: "tools/call",
+ params: {
+ name:,
+ arguments:,
+ },
+ }.to_json,
+ headers: {
+ "HTTP_AUTHORIZATION" => "Bearer #{@token}",
+ "CONTENT_TYPE" => "application/json",
+ "HTTP_ACCEPT" => "application/json, text/event-stream",
+ "HTTP_MCP_PROTOCOL_VERSION" => DiscourseMcp::LEGACY_PROTOCOL_VERSION,
+ }
+ end
+
+ def structured_content
+ response.parsed_body.dig("result", "structuredContent")
+ end
+
+ def make_owner(group, owner)
+ group.add(owner)
+ group.group_users.find_by!(user: owner).update!(owner: true)
+ end
+
+ it "requires the group read scope" do
+ authorize
+
+ {
+ "discourse_list_groups" => {
+ },
+ "discourse_get_group" => {
+ id: 1,
+ },
+ "discourse_list_group_members" => {
+ name: "group",
+ },
+ "discourse_list_group_membership_requests" => {
+ name: "group",
+ },
+ "discourse_list_group_posts" => {
+ name: "group",
+ },
+ }.each do |name, arguments|
+ call_tool(name, arguments)
+ aggregate_failures(name) do
+ expect(response.status).to eq(403)
+ expect(response.headers["WWW-Authenticate"]).to include(
+ 'error="insufficient_scope"',
+ 'scope="mcp:groups:read"',
+ )
+ end
+ end
+ end
+
+ it "lists only groups visible to the user" do
+ visible_group = Fabricate(:group, visibility_level: Group.visibility_levels[:public])
+ hidden_group = Fabricate(:group, visibility_level: Group.visibility_levels[:owners])
+ make_owner(hidden_group, Fabricate(:user))
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_groups", { limit: 100 })
+
+ expect(response.status).to eq(200)
+ expect(structured_content["groups"].pluck("id")).to include(visible_group.id)
+ expect(structured_content["groups"].pluck("id")).not_to include(hidden_group.id)
+ end
+
+ it "does not expose member counts when group membership is private" do
+ group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:owners],
+ )
+ group.add(Fabricate(:user))
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_groups", { limit: 100 })
+
+ group_json = structured_content["groups"].find { |item| item["id"] == group.id }
+ expect(group_json["can_see_members"]).to eq(false)
+ expect(group_json["user_count"]).to be_nil
+ end
+
+ it "does not expose private member counts through group ordering" do
+ prefix = "pc#{SecureRandom.hex(3)}"
+ small_group =
+ Fabricate(
+ :group,
+ name: "#{prefix}_a",
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:owners],
+ )
+ small_group.add(Fabricate(:user))
+ large_group =
+ Fabricate(
+ :group,
+ name: "#{prefix}_z",
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:owners],
+ )
+ 3.times { large_group.add(Fabricate(:user)) }
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_groups", { filter: prefix, order: "user_count", ascending: false })
+
+ expect(structured_content["groups"].pluck("id")).to eq([small_group.id, large_group.id])
+ end
+
+ it "respects the group directory site setting" do
+ SiteSetting.enable_group_directory = false
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_groups")
+ expect(response.status).to eq(403)
+
+ moderator = Fabricate(:moderator, refresh_auto_groups: true)
+ authorize("mcp:groups:read", auth_user: moderator)
+ call_tool("discourse_list_groups")
+ expect(response.status).to eq(200)
+ end
+
+ it "does not reveal a hidden group when the token has scope but the user lacks access" do
+ hidden_group = Fabricate(:group, visibility_level: Group.visibility_levels[:owners])
+ make_owner(hidden_group, Fabricate(:user))
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_get_group", { id: hidden_group.id })
+
+ expect(response.status).to eq(200)
+ expect(response.parsed_body.dig("result", "isError")).to eq(true)
+ expect(response.body).not_to include(hidden_group.name)
+ end
+
+ it "returns the safe group fields exposed by the existing group API" do
+ group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ title: "Group title",
+ full_name: "Group full name",
+ bio_raw: "Group biography",
+ membership_request_template: "Tell us why you want to join",
+ )
+ sign_in(user)
+ get "/groups/#{group.name}.json"
+ api_group = response.parsed_body.fetch("group")
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_get_group", { id: group.id })
+
+ fields = %w[
+ primary_group
+ grant_trust_level
+ flair_url
+ flair_bg_color
+ flair_color
+ bio_cooked
+ default_notification_level
+ membership_request_template
+ publish_read_state
+ mentionable
+ messageable
+ ]
+ expect(structured_content.fetch("group").slice(*fields)).to eq(api_group.slice(*fields))
+ end
+
+ it "gets an automatic group that the existing group API allows the user to see" do
+ automatic_group = Group[:trust_level_0]
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_get_group", { id: automatic_group.id })
+
+ expect(response.status).to eq(200)
+ expect(structured_content.dig("group", "id")).to eq(automatic_group.id)
+ end
+
+ it "does not return group email credentials" do
+ secret = "mcp-group-secret-#{SecureRandom.hex}"
+ group = Fabricate(:group, visibility_level: Group.visibility_levels[:public])
+ group.update_columns(
+ incoming_email: "mcp-#{SecureRandom.hex}@example.com",
+ email_username: "mcp-user-#{SecureRandom.hex}",
+ email_password: secret,
+ )
+ admin = Fabricate(:admin, refresh_auto_groups: true)
+ authorize("mcp:groups:read", auth_user: admin)
+
+ call_tool("discourse_get_group", { id: group.id })
+
+ expect(response.status).to eq(200)
+ expect(response.body).not_to include(secret, group.incoming_email, group.email_username)
+ end
+
+ it "does not add membership queries for each listed group" do
+ Fabricate(:group, visibility_level: Group.visibility_levels[:public])
+ authorize("mcp:groups:read")
+
+ initial_queries =
+ track_sql_queries { call_tool("discourse_list_groups", { limit: 100 }) }.grep(/group_users/i)
+ 5.times { Fabricate(:group, visibility_level: Group.visibility_levels[:public]) }
+ expanded_queries =
+ track_sql_queries { call_tool("discourse_list_groups", { limit: 100 }) }.grep(/group_users/i)
+
+ expect(expanded_queries.size).to be <= initial_queries.size
+ end
+
+ it "applies group directory query modifiers" do
+ visible_group = Fabricate(:group, visibility_level: Group.visibility_levels[:public])
+ filtered_group = Fabricate(:group, visibility_level: Group.visibility_levels[:public])
+ plugin = Plugin::Instance.new
+ modifier = proc { |groups| groups.where.not(id: filtered_group.id) }
+ plugin.register_modifier(:groups_index_query, &modifier)
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_groups", { limit: 100 })
+
+ expect(structured_content["groups"].pluck("id")).to include(visible_group.id)
+ expect(structured_content["groups"].pluck("id")).not_to include(filtered_group.id)
+ ensure
+ DiscoursePluginRegistry.unregister_modifier(plugin, :groups_index_query, &modifier) if plugin
+ end
+
+ it "preserves the difference between moderator and administrator visibility" do
+ hidden_group = Fabricate(:group, visibility_level: Group.visibility_levels[:owners])
+ make_owner(hidden_group, Fabricate(:user))
+ moderator = Fabricate(:moderator, refresh_auto_groups: true)
+ authorize("mcp:groups:read", auth_user: moderator)
+
+ call_tool("discourse_get_group", { id: hidden_group.id })
+ expect(response.parsed_body.dig("result", "isError")).to eq(true)
+
+ admin = Fabricate(:admin, refresh_auto_groups: true)
+ authorize("mcp:groups:read", auth_user: admin)
+ call_tool("discourse_get_group", { id: hidden_group.id })
+
+ expect(response.status).to eq(200)
+ expect(structured_content.dig("group", "id")).to eq(hidden_group.id)
+ end
+
+ it "does not list private members when the token has scope but the user lacks access" do
+ public_group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:public],
+ )
+ visible_member = Fabricate(:user)
+ public_group.add(visible_member)
+ private_group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:owners],
+ )
+ private_member = Fabricate(:user)
+ private_group.add(private_member)
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_group_members", { name: public_group.name })
+ expect(structured_content["members"].pluck("username")).to include(visible_member.username)
+
+ call_tool("discourse_list_group_members", { name: private_group.name })
+ expect(response.status).to eq(403)
+ expect(response.body).not_to include(private_member.username)
+ end
+
+ it "hides activity timestamps for members whose profiles are hidden" do
+ SiteSetting.allow_users_to_hide_profile = true
+ public_group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:public],
+ )
+ hidden_member = Fabricate(:user, last_seen_at: 1.hour.ago, last_posted_at: 2.hours.ago)
+ hidden_member.user_option.update!(hide_profile: true)
+ visible_member = Fabricate(:user, last_seen_at: 3.hours.ago, last_posted_at: 4.hours.ago)
+ public_group.add(hidden_member)
+ public_group.add(visible_member)
+ user.update!(trust_level: TrustLevel[2])
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_group_members", { name: public_group.name })
+
+ members = structured_content["members"]
+ hidden_member_json = members.find { |member| member["id"] == hidden_member.id }
+ visible_member_json = members.find { |member| member["id"] == visible_member.id }
+ expect(hidden_member_json).not_to include("last_seen_at", "last_posted_at")
+ expect(visible_member_json).to include("last_seen_at", "last_posted_at")
+ end
+
+ it "uses the existing group API filtering rules for members" do
+ group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:public],
+ )
+ first_member = Fabricate(:user)
+ second_member = Fabricate(:user)
+ group.add(first_member)
+ group.add(second_member)
+ authorize("mcp:groups:read")
+
+ call_tool(
+ "discourse_list_group_members",
+ { name: group.name, filter: "#{first_member.username},#{second_member.username}" },
+ )
+
+ expect(structured_content["members"].pluck("username")).to contain_exactly(
+ first_member.username,
+ second_member.username,
+ )
+
+ call_tool("discourse_list_group_members", { name: group.name, filter: first_member.email })
+ expect(structured_content["members"]).to be_empty
+
+ admin = Fabricate(:admin, refresh_auto_groups: true)
+ authorize("mcp:groups:read", auth_user: admin)
+ call_tool("discourse_list_group_members", { name: group.name, filter: first_member.email })
+
+ expect(structured_content["members"].pluck("username")).to contain_exactly(
+ first_member.username,
+ )
+ end
+
+ it "requires group management permission even when the token has scope" do
+ managed_group = Fabricate(:group, visibility_level: Group.visibility_levels[:public])
+ make_owner(managed_group, user)
+ managed_group.update!(allow_membership_requests: true)
+ requester = Fabricate(:user)
+ request = Fabricate(:group_request, group: managed_group, user: requester)
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_group_membership_requests", { name: managed_group.name })
+ expect(structured_content["requests"]).to contain_exactly(
+ include("username" => requester.username, "reason" => request.reason),
+ )
+
+ unmanaged_group = Fabricate(:group, visibility_level: Group.visibility_levels[:public])
+ make_owner(unmanaged_group, Fabricate(:user))
+ unmanaged_group.update!(allow_membership_requests: true)
+ hidden_request = Fabricate(:group_request, group: unmanaged_group)
+ call_tool("discourse_list_group_membership_requests", { name: unmanaged_group.name })
+
+ expect(response.status).to eq(403)
+ expect(response.body).not_to include(hidden_request.reason)
+ end
+
+ it "uses the existing group API filtering rules for membership requests" do
+ group = Fabricate(:group, visibility_level: Group.visibility_levels[:public])
+ make_owner(group, user)
+ first_request = Fabricate(:group_request, group:)
+ second_request = Fabricate(:group_request, group:)
+ authorize("mcp:groups:read")
+
+ call_tool(
+ "discourse_list_group_membership_requests",
+ {
+ name: group.name,
+ filter: "#{first_request.user.username},#{second_request.user.username}",
+ },
+ )
+
+ expect(structured_content["requests"].pluck("username")).to contain_exactly(
+ first_request.user.username,
+ second_request.user.username,
+ )
+
+ admin = Fabricate(:admin, refresh_auto_groups: true)
+ authorize("mcp:groups:read", auth_user: admin)
+ call_tool(
+ "discourse_list_group_membership_requests",
+ { name: group.name, filter: first_request.user.email },
+ )
+
+ expect(structured_content["requests"].pluck("username")).to contain_exactly(
+ first_request.user.username,
+ )
+ end
+
+ it "lists only group posts visible to the user" do
+ author_group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:public],
+ )
+ author = Fabricate(:user)
+ author_group.add(author)
+ public_post = Fabricate(:post, user: author)
+ private_category = Fabricate(:private_category, group: Fabricate(:group))
+ private_post =
+ Fabricate(:post, user: author, topic: Fabricate(:topic, category: private_category))
+ private_message = Fabricate(:private_message_post, user: author)
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_group_posts", { name: author_group.name })
+
+ expect(structured_content["posts"].pluck("id")).to include(public_post.id)
+ expect(structured_content["posts"].pluck("id")).not_to include(private_post.id)
+ expect(structured_content["posts"].pluck("id")).not_to include(private_message.id)
+ end
+
+ it "paginates group posts when IDs and creation times have different orders" do
+ group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:public],
+ )
+ author = Fabricate(:user)
+ group.add(author)
+ newest_post = Fabricate(:post, user: author, created_at: 1.day.ago)
+ shared_created_at = 2.days.ago
+ lower_id_post = Fabricate(:post, user: author, created_at: shared_created_at)
+ higher_id_post = Fabricate(:post, user: author, created_at: shared_created_at)
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_group_posts", { name: group.name, limit: 1 })
+
+ expect(structured_content["posts"].pluck("id")).to eq([newest_post.id])
+ expect(structured_content.dig("meta", "has_more")).to eq(true)
+ cursor = structured_content.dig("meta", "next_before_post_id")
+
+ call_tool("discourse_list_group_posts", { name: group.name, limit: 1, before_post_id: cursor })
+
+ expect(structured_content["posts"].pluck("id")).to eq([higher_id_post.id])
+ expect(structured_content.dig("meta", "has_more")).to eq(true)
+
+ cursor = structured_content.dig("meta", "next_before_post_id")
+ call_tool("discourse_list_group_posts", { name: group.name, limit: 1, before_post_id: cursor })
+
+ expect(structured_content["posts"].pluck("id")).to eq([lower_id_post.id])
+ expect(structured_content.dig("meta", "has_more")).to eq(false)
+ end
+
+ it "rejects multiple group post cursors" do
+ group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:public],
+ )
+ authorize("mcp:groups:read")
+
+ call_tool(
+ "discourse_list_group_posts",
+ { name: group.name, before_post_id: 1, before: 1.day.ago.iso8601 },
+ )
+
+ expect(response.status).to eq(200)
+ expect(response.parsed_body.dig("result", "isError")).to eq(true)
+ expect(response.body).to include(I18n.t("mcp.errors.group_post_single_cursor"))
+ end
+
+ it "does not list group posts when the token has scope but the user cannot see members" do
+ group =
+ Fabricate(
+ :group,
+ visibility_level: Group.visibility_levels[:public],
+ members_visibility_level: Group.visibility_levels[:owners],
+ )
+ author = Fabricate(:user)
+ group.add(author)
+ post = Fabricate(:post, user: author)
+ authorize("mcp:groups:read")
+
+ call_tool("discourse_list_group_posts", { name: group.name })
+
+ expect(response.status).to eq(403)
+ expect(response.body).not_to include(post.topic.title)
+ end
+end