Skip to content

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

FEATURE: Add output schemas to MCP tools (#43573)

Natalie Taya8bf09aadd6d
diff --git a/lib/discourse_mcp/core_primitives.rb b/lib/discourse_mcp/core_primitives.rb
index 5cc0a6b4ef4..3a86c388f85 100644
--- a/lib/discourse_mcp/core_primitives.rb
+++ b/lib/discourse_mcp/core_primitives.rb
@@ -33,6 +33,15 @@ module DiscourseMcp
{ type: "object", properties: properties, required: required, additionalProperties: false }
end
+ def register_tool(registry, identifier, implementation:, **attributes)
+ registry.register_tool(
+ identifier,
+ implementation:,
+ output_schema: implementation::OUTPUT_SCHEMA,
+ **attributes,
+ )
+ end
+
def register!
registry = DiscourseMcp.registry
register_read_tools(registry)
@@ -42,7 +51,8 @@ module DiscourseMcp
end
def register_read_tools(registry)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_current_user_get",
title: "Get current user",
description:
@@ -51,7 +61,8 @@ module DiscourseMcp
required_scopes: [DiscourseMcp::INITIAL_SCOPE],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_search",
title: "Search Discourse",
description:
@@ -77,7 +88,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_filter_topics",
title: "Filter topics",
description:
@@ -117,7 +129,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_search_posts",
title: "Search posts",
description:
@@ -145,7 +158,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_read_topic_posts",
title: "Read selected topic posts",
description:
@@ -201,7 +215,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_get_post_replies",
title: "Get post replies",
description:
@@ -231,7 +246,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_list_latest_posts",
title: "List latest posts",
description:
@@ -245,7 +261,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_get_topic_view_stats",
title: "Get topic view stats",
description:
@@ -273,7 +290,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_list_directory_items",
title: "List directory items",
description:
@@ -338,7 +356,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_read_topic",
title: "Read topic",
description: "Reads a topic and a bounded set of posts visible to the authenticated user.",
@@ -366,7 +385,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_read_post",
title: "Read post",
description: "Reads one visible post.",
@@ -376,7 +396,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_topic_list",
title: "List topics",
description: "Lists recent topics visible to the authenticated user.",
@@ -385,7 +406,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_category_list",
title: "List categories",
description: "Lists the visible category hierarchy.",
@@ -393,7 +415,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_tag_list",
title: "List tags",
description: "Lists visible tags ordered by usage.",
@@ -402,7 +425,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_get_user",
title: "Get user",
description: "Reads a user profile visible to the authenticated user.",
@@ -415,7 +439,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_list_user_posts",
title: "List user posts",
description: "Lists a user's visible topics and replies with zero-based pagination.",
@@ -443,7 +468,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_get_user_summary",
title: "Get user summary",
description: "Returns profile-visible aggregate activity for a user.",
@@ -456,7 +482,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_list_user_actions",
title: "List user actions",
description: "Lists a user's visible activity using named action types.",
@@ -498,7 +525,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_get_draft",
title: "Get draft",
description: "Retrieves one of the authenticated user's drafts by key.",
@@ -521,7 +549,8 @@ module DiscourseMcp
required_scopes: %w[mcp:drafts:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_bookmark_list",
title: "List bookmarks",
description: "Lists the authenticated user's bookmarks.",
@@ -530,7 +559,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_notification_list",
title: "List notifications",
description: "Lists the authenticated user's notifications.",
@@ -539,7 +569,8 @@ module DiscourseMcp
required_scopes: %w[mcp:content:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_list_private_messages",
title: "List private messages",
description: "Lists a personal or group private-message mailbox visible to the user.",
@@ -578,7 +609,8 @@ module DiscourseMcp
required_scopes: %w[mcp:private-messages:read],
annotations: READ_ONLY,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_read_private_message",
title: "Read private message",
description: "Reads a private message visible to the authenticated user.",
@@ -609,7 +641,8 @@ module DiscourseMcp
end
def register_write_tools(registry)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_create_topic",
title: "Create topic",
description: "Creates a topic as the authenticated user.",
@@ -649,7 +682,8 @@ module DiscourseMcp
annotations: WRITE,
risk: :write,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_create_post",
title: "Create post",
description: "Creates a reply in a topic as the authenticated user.",
@@ -682,7 +716,8 @@ module DiscourseMcp
annotations: WRITE,
risk: :write,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_update_post",
title: "Update post",
description: "Edits a post when the authenticated user has permission.",
@@ -710,7 +745,8 @@ module DiscourseMcp
annotations: WRITE,
risk: :write,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_update_topic",
title: "Update topic",
description: "Updates fields on a topic when the user may edit it.",
@@ -764,7 +800,8 @@ module DiscourseMcp
annotations: WRITE,
risk: :write,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_update_user",
title: "Update user",
description: "Updates the authenticated user's own profile.",
@@ -824,7 +861,8 @@ module DiscourseMcp
annotations: WRITE,
risk: :write,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_upload_file",
title: "Upload file",
description: "Uploads base64 data or a remote HTTP(S) file for the authenticated user.",
@@ -861,7 +899,8 @@ module DiscourseMcp
annotations: EXTERNAL_SIDE_EFFECT,
risk: :external_side_effect,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_create_private_message",
title: "Create private message",
description: "Creates a private message as the authenticated user.",
@@ -917,7 +956,8 @@ module DiscourseMcp
annotations: EXTERNAL_SIDE_EFFECT,
risk: :external_side_effect,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_reply_private_message",
title: "Reply to private message",
description: "Replies to a private message visible to the authenticated user.",
@@ -950,7 +990,8 @@ module DiscourseMcp
annotations: WRITE,
risk: :write,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_invite_to_private_message",
title: "Invite to private message",
description:
@@ -997,7 +1038,8 @@ module DiscourseMcp
annotations: EXTERNAL_SIDE_EFFECT,
risk: :external_side_effect,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_post_set_deleted",
title: "Delete or recover own post",
description: "Deletes or recovers a post owned by the authenticated user.",
@@ -1011,7 +1053,8 @@ module DiscourseMcp
annotations: DESTRUCTIVE,
risk: :destructive,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_save_draft",
title: "Save draft",
description: "Creates or updates a draft for the authenticated user.",
@@ -1063,7 +1106,8 @@ module DiscourseMcp
annotations: WRITE,
risk: :write,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_delete_draft",
title: "Delete draft",
description: "Deletes one of the authenticated user's drafts at its current sequence.",
@@ -1087,7 +1131,8 @@ module DiscourseMcp
annotations: DESTRUCTIVE,
risk: :destructive,
)
- registry.register_tool(
+ register_tool(
+ registry,
"discourse_user_status_set",
title: "Set user status",
description: "Sets or clears the authenticated user's status.",
diff --git a/lib/discourse_mcp/core_tools.rb b/lib/discourse_mcp/core_tools.rb
index 2c6e2978538..054a2261cf4 100644
--- a/lib/discourse_mcp/core_tools.rb
+++ b/lib/discourse_mcp/core_tools.rb
@@ -1,6 +1,7 @@
# frozen_string_literal: true
require "discourse_mcp/tool_helpers"
+require "discourse_mcp/output_schema"
require "discourse_mcp/tools/search"
require "discourse_mcp/tools/topic_reads"
require "discourse_mcp/tools/topic_writes"
diff --git a/lib/discourse_mcp/output_schema.rb b/lib/discourse_mcp/output_schema.rb
new file mode 100644
index 00000000000..b3d500abc38
--- /dev/null
+++ b/lib/discourse_mcp/output_schema.rb
@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module DiscourseMcp
+ module OutputSchema
+ ANY = {}.freeze
+ STRING = { type: "string" }.freeze
+ INTEGER = { type: "integer" }.freeze
+ BOOLEAN = { type: "boolean" }.freeze
+ STRING_OR_NULL = { type: %w[string null] }.freeze
+ INTEGER_OR_NULL = { type: %w[integer null] }.freeze
+ BOOLEAN_OR_NULL = { type: %w[boolean null] }.freeze
+ ARRAY = { type: "array" }.freeze
+ STRING_ARRAY = { type: "array", items: STRING }.freeze
+ OBJECT_ARRAY = { type: "array", items: { type: "object" } }.freeze
+ OBJECT = { type: "object" }.freeze
+
+ module_function
+
+ def object(optional: [], **properties)
+ {
+ type: "object",
+ properties:,
+ required: properties.keys.map(&:to_s) - optional,
+ additionalProperties: false,
+ }
+ end
+ end
+end
diff --git a/lib/discourse_mcp/tools/bookmarks.rb b/lib/discourse_mcp/tools/bookmarks.rb
index 26c912b1df0..dd8dbf7ea86 100644
--- a/lib/discourse_mcp/tools/bookmarks.rb
+++ b/lib/discourse_mcp/tools/bookmarks.rb
@@ -3,6 +3,8 @@
module DiscourseMcp
module Tools
class ListBookmarks
+ OUTPUT_SCHEMA = OutputSchema.object(bookmarks: OutputSchema::OBJECT_ARRAY)
+
def self.call(arguments:, request_context:)
bookmarks =
Bookmark
diff --git a/lib/discourse_mcp/tools/drafts.rb b/lib/discourse_mcp/tools/drafts.rb
index b1704987738..1972ec091d3 100644
--- a/lib/discourse_mcp/tools/drafts.rb
+++ b/lib/discourse_mcp/tools/drafts.rb
@@ -3,6 +3,15 @@
module DiscourseMcp
module Tools
class GetDraft
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ optional: %w[sequence data],
+ draft_key: OutputSchema::STRING,
+ sequence: OutputSchema::INTEGER,
+ found: OutputSchema::BOOLEAN,
+ data: OutputSchema::OBJECT,
+ )
+
def self.call(arguments:, request_context:)
user = request_context.user or raise Discourse::InvalidAccess
draft_key = arguments.fetch("draft_key")
@@ -49,6 +58,13 @@ module DiscourseMcp
end
class SaveDraft
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ draft_key: OutputSchema::STRING,
+ sequence: OutputSchema::INTEGER,
+ saved: OutputSchema::BOOLEAN,
+ )
+
def self.call(arguments:, request_context:)
user = request_context.user or raise Discourse::InvalidAccess
draft_key = arguments.fetch("draft_key")
@@ -89,6 +105,9 @@ module DiscourseMcp
end
class DeleteDraft
+ OUTPUT_SCHEMA =
+ OutputSchema.object(draft_key: OutputSchema::STRING, deleted: OutputSchema::BOOLEAN)
+
def self.call(arguments:, request_context:)
user = request_context.user or raise Discourse::InvalidAccess
draft_key = arguments.fetch("draft_key")
diff --git a/lib/discourse_mcp/tools/notifications.rb b/lib/discourse_mcp/tools/notifications.rb
index e5b16ef2c8c..ab34227f459 100644
--- a/lib/discourse_mcp/tools/notifications.rb
+++ b/lib/discourse_mcp/tools/notifications.rb
@@ -3,6 +3,8 @@
module DiscourseMcp
module Tools
class ListNotifications
+ OUTPUT_SCHEMA = OutputSchema.object(notifications: OutputSchema::OBJECT_ARRAY)
+
def self.call(arguments:, request_context:)
limit = arguments.fetch("limit", 50).to_i.clamp(1, 100)
notifications =
diff --git a/lib/discourse_mcp/tools/private_messages.rb b/lib/discourse_mcp/tools/private_messages.rb
index 262f55d0e88..f48c9681a57 100644
--- a/lib/discourse_mcp/tools/private_messages.rb
+++ b/lib/discourse_mcp/tools/private_messages.rb
@@ -4,6 +4,14 @@ module DiscourseMcp
module Tools
class ListPrivateMessages
MAILBOXES = %w[inbox sent archive unread new].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ mailbox: OutputSchema::STRING,
+ username: OutputSchema::STRING,
+ group_name: OutputSchema::STRING_OR_NULL,
+ messages: OutputSchema::OBJECT_ARRAY,
+ meta: OutputSchema::OBJECT,
+ )
def self.call(arguments:, request_context:)
mailbox = arguments.fetch("mailbox", "inbox")
@@ -132,6 +140,23 @@ module DiscourseMcp
end
class ReadPrivateMessage
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ topic_id: OutputSchema::INTEGER,
+ slug: OutputSchema::STRING,
+ title: OutputSchema::STRING,
+ archetype: OutputSchema::STRING,
+ subtype: OutputSchema::STRING_OR_NULL,
+ posts_count: OutputSchema::INTEGER,
+ last_read_post_number: OutputSchema::INTEGER_OR_NULL,
+ topic_archived: OutputSchema::BOOLEAN,
+ message_archived: OutputSchema::BOOLEAN,
+ allowed_users: OutputSchema::OBJECT_ARRAY,
+ allowed_groups: OutputSchema::OBJECT_ARRAY,
+ posts: OutputSchema::OBJECT_ARRAY,
+ meta: OutputSchema::OBJECT,
+ )
+
def self.call(arguments:, request_context:)
topic = private_message_topic!(arguments.fetch("topic_id"), request_context.guardian)
start_post_number = arguments.fetch("start_post_number", 1)
@@ -187,6 +212,15 @@ module DiscourseMcp
end
class CreatePrivateMessage
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ id: OutputSchema::INTEGER,
+ topic_id: OutputSchema::INTEGER,
+ post_number: OutputSchema::INTEGER,
+ slug: OutputSchema::STRING,
+ title: OutputSchema::STRING,
+ )
+
def self.call(arguments:, request_context:)
ToolHelpers.ensure_current_author!(arguments, request_context.user)
usernames = Array(arguments["usernames"])
@@ -234,6 +268,15 @@ module DiscourseMcp
end
class ReplyPrivateMessage
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ id: OutputSchema::INTEGER,
+ topic_id: OutputSchema::INTEGER,
+ post_number: OutputSchema::INTEGER,
+ reply_to_post_number: OutputSchema::INTEGER_OR_NULL,
+ slug: OutputSchema::STRING,
+ )
+
def self.call(arguments:, request_context:)
ToolHelpers.ensure_current_author!(arguments, request_context.user)
topic =
@@ -259,6 +302,19 @@ module DiscourseMcp
end
class InviteToPrivateMessage
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ optional: %w[group notifications_requested user participant_added outcome_confirmed],
+ topic_id: OutputSchema::INTEGER,
+ recipient_type: OutputSchema::STRING,
+ status: OutputSchema::STRING,
+ group: OutputSchema::OBJECT,
+ notifications_requested: OutputSchema::BOOLEAN,
+ user: OutputSchema::OBJECT,
+ participant_added: OutputSchema::BOOLEAN,
+ outcome_confirmed: OutputSchema::BOOLEAN,
+ )
+
def self.call(arguments:, request_context:)
ToolHelpers.ensure_current_author!(arguments, request_context.user)
topic =
diff --git a/lib/discourse_mcp/tools/search.rb b/lib/discourse_mcp/tools/search.rb
index a5167b272eb..77f11bc9431 100644
--- a/lib/discourse_mcp/tools/search.rb
+++ b/lib/discourse_mcp/tools/search.rb
@@ -3,6 +3,9 @@
module DiscourseMcp
module Tools
class Search
+ OUTPUT_SCHEMA =
+ OutputSchema.object(results: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)
+
def self.call(arguments:, request_context:)
query = arguments.fetch("query").to_s
limit = arguments.fetch("max_results", 10)
@@ -22,6 +25,8 @@ module DiscourseMcp
class FilterTopics
TOP_PERIODS = %w[daily weekly monthly quarterly yearly all].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(results: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)
def self.call(arguments:, request_context:)
view = arguments.fetch("view", "filtered")
@@ -87,6 +92,17 @@ module DiscourseMcp
end
class SearchPosts
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ posts: OutputSchema::OBJECT_ARRAY,
+ topics: OutputSchema::OBJECT_ARRAY,
+ users: OutputSchema::OBJECT_ARRAY,
+ categories: OutputSchema::OBJECT_ARRAY,
+ groups: OutputSchema::ARRAY,
+ tags: OutputSchema::STRING_ARRAY,
+ meta: OutputSchema::OBJECT,
+ )
+
def self.call(arguments:, request_context:)
query = arguments.fetch("query")
page = arguments.fetch("page", 1)
diff --git a/lib/discourse_mcp/tools/topic_reads.rb b/lib/discourse_mcp/tools/topic_reads.rb
index c35cdbebd8b..065addb2d98 100644
--- a/lib/discourse_mcp/tools/topic_reads.rb
+++ b/lib/discourse_mcp/tools/topic_reads.rb
@@ -10,6 +10,13 @@ module DiscourseMcp
"around_post" => %w[post_number limit],
"usernames" => %w[usernames limit replies_only],
}.freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ topic_id: OutputSchema::INTEGER,
+ selection_mode: OutputSchema::STRING,
+ posts: OutputSchema::OBJECT_ARRAY,
+ meta: OutputSchema::OBJECT,
+ )
def self.call(arguments:, request_context:)
validate_selection!(arguments)
@@ -132,6 +139,15 @@ module DiscourseMcp
class GetPostReplies
DIRECT_REPLIES_LIMIT = 20
MODES = %w[reply_ids direct_replies reply_history].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ optional: %w[posts replies],
+ post_id: OutputSchema::INTEGER,
+ mode: OutputSchema::STRING,
+ posts: OutputSchema::OBJECT_ARRAY,
+ replies: OutputSchema::OBJECT_ARRAY,
+ meta: OutputSchema::OBJECT,
+ )
def self.call(arguments:, request_context:)
guardian = request_context.guardian
@@ -237,6 +253,9 @@ module DiscourseMcp
end
class ListLatestPosts
+ OUTPUT_SCHEMA =
+ OutputSchema.object(posts: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)
+
def self.call(arguments:, request_context:)
before_post_id = arguments["before_post_id"]
posts =
@@ -278,6 +297,13 @@ module DiscourseMcp
end
class GetTopicViewStats
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ topic_id: OutputSchema::INTEGER,
+ view_stats: OutputSchema::OBJECT_ARRAY,
+ meta: OutputSchema::OBJECT,
+ )
+
def self.call(arguments:, request_context:)
topic = Topic.find_by(id: arguments.fetch("topic_id"))
if topic.blank? || !request_context.guardian.can_see?(topic)
@@ -317,6 +343,23 @@ module DiscourseMcp
end
class GetTopic
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ id: OutputSchema::INTEGER,
+ title: OutputSchema::STRING,
+ slug: OutputSchema::STRING,
+ category_id: OutputSchema::INTEGER_OR_NULL,
+ tags: OutputSchema::STRING_ARRAY,
+ posts_count: OutputSchema::INTEGER,
+ created_at: OutputSchema::STRING,
+ last_posted_at: OutputSchema::STRING_OR_NULL,
+ closed: OutputSchema::BOOLEAN,
+ archived: OutputSchema::BOOLEAN,
+ url: OutputSchema::STRING,
+ posts: OutputSchema::OBJECT_ARRAY,
+ meta: OutputSchema::OBJECT,
+ )
+
def self.call(arguments:, request_context:)
topic = Topic.find_by(id: arguments.fetch("topic_id").to_i)
if topic.blank? || !request_context.guardian.can_see?(topic)
@@ -351,6 +394,21 @@ module DiscourseMcp
end
class GetPost
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ optional: %w[accepted_answer topic_accepted_answer],
+ id: OutputSchema::INTEGER,
+ topic_id: OutputSchema::INTEGER,
+ topic_slug: OutputSchema::STRING_OR_NULL,
+ post_number: OutputSchema::INTEGER,
+ username: OutputSchema::STRING_OR_NULL,
+ created_at: OutputSchema::STRING,
+ raw: OutputSchema::STRING,
+ truncated: OutputSchema::BOOLEAN,
+ accepted_answer: OutputSchema::BOOLEAN_OR_NULL,
+ topic_accepted_answer: OutputSchema::BOOLEAN_OR_NULL,
+ )
+
def self.call(arguments:, request_context:)
post = ToolHelpers.visible_post!(arguments.fetch("post_id"), request_context.guardian)
result =
@@ -371,6 +429,8 @@ module DiscourseMcp
end
class ListTopics
+ OUTPUT_SCHEMA = OutputSchema.object(topics: OutputSchema::OBJECT_ARRAY)
+
def self.call(arguments:, request_context:)
limit = arguments.fetch("limit", 30).to_i.clamp(1, 50)
topics = TopicQuery.new(request_context.user).list_latest.topics.first(limit)
@@ -386,6 +446,8 @@ module DiscourseMcp
end
class ListCategories
+ OUTPUT_SCHEMA = OutputSchema.object(categories: OutputSchema::OBJECT_ARRAY)
+
def self.call(arguments:, request_context:)
categories = Category.secured(request_context.guardian).order(:position, :id).limit(500)
ToolHelpers.text_and_structured(
@@ -404,6 +466,8 @@ module DiscourseMcp
end
class ListTags
+ OUTPUT_SCHEMA = OutputSchema.object(tags: OutputSchema::OBJECT_ARRAY)
+
def self.call(arguments:, request_context:)
column = Tag.topic_count_column(request_context.guardian)
tags = Tag.order(column => :desc).limit(arguments.fetch("limit", 100).to_i.clamp(1, 200))
diff --git a/lib/discourse_mcp/tools/topic_writes.rb b/lib/discourse_mcp/tools/topic_writes.rb
index d7cb4fbba75..c05891bcdc0 100644
--- a/lib/discourse_mcp/tools/topic_writes.rb
+++ b/lib/discourse_mcp/tools/topic_writes.rb
@@ -3,6 +3,17 @@
module DiscourseMcp
module Tools
class CreateTopic
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ id: OutputSchema::INTEGER,
+ topic_id: OutputSchema::INTEGER,
+ slug: OutputSchema::STRING,
+ title: OutputSchema::STRING,
+ username: OutputSchema::STRING,
+ requested_author: OutputSchema::STRING_OR_NULL,
+ author_applied: OutputSchema::BOOLEAN_OR_NULL,
+ )
+
def self.call(arguments:, request_context:)
ToolHelpers.ensure_current_author!(arguments, request_context.user)
post =
@@ -29,6 +40,16 @@ module DiscourseMcp
end
class ReplyTopic
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ id: OutputSchema::INTEGER,
+ topic_id: OutputSchema::INTEGER,
+ post_number: OutputSchema::INTEGER,
+ username: OutputSchema::STRING,
+ requested_author: OutputSchema::STRING_OR_NULL,
+ author_applied: OutputSchema::BOOLEAN_OR_NULL,
+ )
+
def self.call(arguments:, request_context:)
ToolHelpers.ensure_current_author!(arguments, request_context.user)
post =
@@ -52,6 +73,16 @@ module DiscourseMcp
end
class EditPost
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ id: OutputSchema::INTEGER,
+ topic_id: OutputSchema::INTEGER,
+ post_number: OutputSchema::INTEGER,
+ raw: OutputSchema::STRING,
+ updated_at: OutputSchema::STRING,
+ edit_reason: OutputSchema::STRING_OR_NULL,
+ )
+
def self.call(arguments:, request_context:)
post = Post.find_by(id: arguments.fetch("post_id").to_i)
if post.blank? || !request_context.guardian.can_edit_post?(post)
@@ -76,6 +107,13 @@ module DiscourseMcp
class UpdateTopic
MUTABLE_FIELDS = %w[title category_id tags featured_link].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ success: OutputSchema::BOOLEAN,
+ topic_id: OutputSchema::INTEGER,
+ updated_fields: OutputSchema::STRING_ARRAY,
+ topic: OutputSchema::OBJECT,
+ )
def self.call(arguments:, request_context:)
topic = Topic.find_by(id: arguments.fetch("topic_id"))
@@ -175,6 +213,9 @@ module DiscourseMcp
end
class SetPostDeleted
+ OUTPUT_SCHEMA =
+ OutputSchema.object(post_id: OutputSchema::INTEGER, deleted: OutputSchema::BOOLEAN)
+
def self.call(arguments:, request_context:)
post = Post.find_by(id: arguments.fetch("post_id").to_i, user_id: request_context.user_id)
raise DiscourseMcp::ToolError, "Post not found" if post.blank?
diff --git a/lib/discourse_mcp/tools/uploads.rb b/lib/discourse_mcp/tools/uploads.rb
index 6ab061ecb07..ca71d91734d 100644
--- a/lib/discourse_mcp/tools/uploads.rb
+++ b/lib/discourse_mcp/tools/uploads.rb
@@ -7,6 +7,20 @@ module DiscourseMcp
module Tools
class UploadFile
UPLOAD_TYPES = %w[avatar profile_background card_background composer].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ optional: %w[short_url short_path extension width height filesize human_filesize],
+ id: OutputSchema::INTEGER,
+ url: OutputSchema::STRING,
+ short_url: OutputSchema::STRING,
+ short_path: OutputSchema::STRING,
+ original_filename: OutputSchema::STRING,
+ extension: OutputSchema::STRING_OR_NULL,
+ width: OutputSchema::INTEGER_OR_NULL,
+ height: OutputSchema::INTEGER_OR_NULL,
+ filesize: OutputSchema::INTEGER,
+ human_filesize: OutputSchema::STRING,
+ )
def self.call(arguments:, request_context:)
user = request_context.user or raise Discourse::InvalidAccess
diff --git a/lib/discourse_mcp/tools/users.rb b/lib/discourse_mcp/tools/users.rb
index 5a7201fd9bd..73824efbef2 100644
--- a/lib/discourse_mcp/tools/users.rb
+++ b/lib/discourse_mcp/tools/users.rb
@@ -5,6 +5,18 @@ require "directory_items_query"
module DiscourseMcp
module Tools
class CurrentUser
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ id: OutputSchema::INTEGER,
+ username: OutputSchema::STRING,
+ name: OutputSchema::STRING_OR_NULL,
+ trust_level: OutputSchema::INTEGER,
+ admin: OutputSchema::BOOLEAN,
+ moderator: OutputSchema::BOOLEAN,
+ scopes: OutputSchema::STRING_ARRAY,
+ resource: OutputSchema::STRING,
+ )
+
def self.call(arguments:, request_context:)
user = request_context.user or raise Discourse::InvalidAccess
ToolHelpers.text_and_structured(
@@ -23,6 +35,8 @@ module DiscourseMcp
class ListDirectoryItems
PAGE_SIZE = ::DirectoryItemsQuery::PAGE_SIZE
PAGE_LIMIT = ::DirectoryItemsQuery::PAGE_LIMIT
+ OUTPUT_SCHEMA =
+ OutputSchema.object(directory_items: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)
def self.call(arguments:, request_context:)
unless SiteSetting.enable_user_directory?
@@ -104,6 +118,18 @@ module DiscourseMcp
end
class GetUser
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ id: OutputSchema::INTEGER,
+ username: OutputSchema::STRING,
+ name: OutputSchema::STRING_OR_NULL,
+ trust_level: OutputSchema::INTEGER,
+ created_at: OutputSchema::STRING,
+ bio: OutputSchema::STRING,
+ admin: OutputSchema::BOOLEAN,
+ moderator: OutputSchema::BOOLEAN,
+ )
+
def self.call(arguments:, request_context:)
user = ToolHelpers.visible_user!(arguments.fetch("username"), request_context.guardian)
@@ -122,6 +148,9 @@ module DiscourseMcp
end
class ListUserPosts
+ OUTPUT_SCHEMA =
+ OutputSchema.object(posts: OutputSchema::OBJECT_ARRAY, meta: OutputSchema::OBJECT)
+
def self.call(arguments:, request_context:)
guardian = request_context.guardian
user = ToolHelpers.visible_user!(arguments.fetch("username"), guardian)
@@ -163,6 +192,30 @@ module DiscourseMcp
can_see_summary_stats
can_see_user_actions
].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ username: OutputSchema::STRING,
+ likes_given: OutputSchema::ANY,
+ likes_received: OutputSchema::ANY,
+ topics_entered: OutputSchema::ANY,
+ posts_read_count: OutputSchema::ANY,
+ days_visited: OutputSchema::ANY,
+ topic_count: OutputSchema::ANY,
+ post_count: OutputSchema::ANY,
+ time_read: OutputSchema::ANY,
+ recent_time_read: OutputSchema::ANY,
+ bookmark_count: OutputSchema::ANY,
+ can_see_summary_stats: OutputSchema::ANY,
+ can_see_user_actions: OutputSchema::ANY,
+ top_topics: OutputSchema::OBJECT_ARRAY,
+ top_replies: OutputSchema::OBJECT_ARRAY,
+ top_links: OutputSchema::OBJECT_ARRAY,
+ most_liked_by_users: OutputSchema::OBJECT_ARRAY,
+ most_liked_users: OutputSchema::OBJECT_ARRAY,
+ most_replied_to_users: OutputSchema::OBJECT_ARRAY,
+ top_categories: OutputSchema::OBJECT_ARRAY,
+ badges: OutputSchema::OBJECT_ARRAY,
+ )
def self.call(arguments:, request_context:)
guardian = request_context.guardian
@@ -201,6 +254,12 @@ module DiscourseMcp
"linked" => 17,
}.freeze
ACTION_NAMES = ACTION_TYPES.invert.freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ actions: OutputSchema::OBJECT_ARRAY,
+ categories: OutputSchema::OBJECT_ARRAY,
+ meta: OutputSchema::OBJECT,
+ )
def self.call(arguments:, request_context:)
guardian = request_context.guardian
@@ -289,6 +348,14 @@ module DiscourseMcp
profile_background_upload_url
card_background_upload_url
].freeze
+ OUTPUT_SCHEMA =
+ OutputSchema.object(
+ success: OutputSchema::BOOLEAN,
+ username: OutputSchema::STRING,
+ updated_fields: OutputSchema::STRING_ARRAY,
+ avatar_updated: OutputSchema::BOOLEAN,
+ user: OutputSchema::OBJECT,
+ )
def self.call(arguments:, request_context:)
user = User.find_by_username(arguments.fetch("username"))
@@ -362,6 +429,8 @@ module DiscourseMcp
end
class SetUserStatus
+ OUTPUT_SCHEMA = OutputSchema.object(success: OutputSchema::BOOLEAN)
+
def self.call(arguments:, request_context:)
user = request_context.user or raise Discourse::InvalidAccess
if arguments.fetch("clear", false)
diff --git a/plugins/chat/lib/chat/mcp_tools.rb b/plugins/chat/lib/chat/mcp_tools.rb
index e2084e55b0b..3a5baaeefd6 100644
--- a/plugins/chat/lib/chat/mcp_tools.rb
+++ b/plugins/chat/lib/chat/mcp_tools.rb
@@ -3,6 +3,20 @@
module Chat
module McpTools
class ListChannels
+ OUTPUT_SCHEMA =
+ DiscourseMcp::OutputSchema.object(
+ channels: {
+ type: "array",
+ items:
+ DiscourseMcp::OutputSchema.object(
+ id: DiscourseMcp::OutputSchema::INTEGER,
+ title: DiscourseMcp::OutputSchema::STRING,
+ status: DiscourseMcp::OutputSchema::STRING,
+ direct_message: DiscourseMcp::OutputSchema::BOOLEAN,
+ ),
+ },
+ )
+
def self.call(arguments:, request_context:)
result = Chat::ListUserChannels.call(guardian: request_context.guardian)
raise DiscourseMcp::ToolError, "Unable to list chat channels" if result.failure?
@@ -21,6 +35,27 @@ module Chat
end
class ListMessages
+ OUTPUT_SCHEMA =
+ DiscourseMcp::OutputSchema.object(
+ channel_id: DiscourseMcp::OutputSchema::INTEGER,
+ messages: {
+ type: "array",
+ items:
+ DiscourseMcp::OutputSchema.object(
+ id: DiscourseMcp::OutputSchema::INTEGER,
+ channel_id: DiscourseMcp::OutputSchema::INTEGER,
+ user_id: DiscourseMcp::OutputSchema::INTEGER_OR_NULL,
+ username: DiscourseMcp::OutputSchema::STRING_OR_NULL,
+ message: DiscourseMcp::OutputSchema::STRING,
+ created_at: DiscourseMcp::OutputSchema::STRING,
+ edited: DiscourseMcp::OutputSchema::BOOLEAN,
+ thread_id: DiscourseMcp::OutputSchema::INTEGER_OR_NULL,
+ in_reply_to_id: DiscourseMcp::OutputSchema::INTEGER_OR_NULL,
+ ),
+ },
+ meta: DiscourseMcp::OutputSchema::OBJECT,
+ )
+
def self.call(arguments:, request_context:)
result =
Chat::ListChannelMessages.call(
@@ -63,6 +98,13 @@ module Chat
end
class CreateMessage
+ OUTPUT_SCHEMA =
+ DiscourseMcp::OutputSchema.object(
+ id: DiscourseMcp::OutputSchema::INTEGER,
+ channel_id: DiscourseMcp::OutputSchema::INTEGER,
+ created_at: DiscourseMcp::OutputSchema::STRING,
+ )
+
def self.call(arguments:, request_context:)
result =
Chat::CreateMessage.call(
diff --git a/plugins/chat/plugin.rb b/plugins/chat/plugin.rb
index 2f4f54c7332..41b81c13898 100644
--- a/plugins/chat/plugin.rb
+++ b/plugins/chat/plugin.rb
@@ -657,6 +657,7 @@ after_initialize do
description:
"Lists chat channels followed by the authenticated user, including direct-message channels.",
implementation: Chat::McpTools::ListChannels,
+ output_schema: Chat::McpTools::ListChannels::OUTPUT_SCHEMA,
required_scopes: %w[chat:read],
annotations: {
readOnlyHint: true,
@@ -698,6 +699,7 @@ after_initialize do
required: ["channel_id"],
additionalProperties: false,
},
+ output_schema: Chat::McpTools::ListMessages::OUTPUT_SCHEMA,
required_scopes: %w[chat:read],
annotations: {
readOnlyHint: true,
@@ -731,6 +733,7 @@ after_initialize do
required: %w[channel_id message],
additionalProperties: false,
},
+ output_schema: Chat::McpTools::CreateMessage::OUTPUT_SCHEMA,
required_scopes: %w[chat:write],
annotations: {
readOnlyHint: false,
diff --git a/plugins/discourse-events/lib/discourse_events/mcp_tools.rb b/plugins/discourse-events/lib/discourse_events/mcp_tools.rb
index ab77e9f8b3f..921df05df27 100644
--- a/plugins/discourse-events/lib/discourse_events/mcp_tools.rb
+++ b/plugins/discourse-events/lib/discourse_events/mcp_tools.rb
@@ -3,6 +3,23 @@
module DiscourseEvents
module McpTools
class ListEvents
+ OUTPUT_SCHEMA =
+ DiscourseMcp::OutputSchema.object(
+ events: {
+ type: "array",
+ items:
+ DiscourseMcp::OutputSchema.object(
+ id: DiscourseMcp::OutputSchema::INTEGER,
+ post_id: DiscourseMcp::OutputSchema::INTEGER,
+ topic_id: DiscourseMcp::OutputSchema::INTEGER,
+ name: DiscourseMcp::OutputSchema::STRING,
+ starts_at: DiscourseMcp::OutputSchema::STRING_OR_NULL,
+ ends_at: DiscourseMcp::OutputSchema::STRING_OR_NULL,
+ status: DiscourseMcp::OutputSchema::ANY,
+ ),
+ },
+ )
+
def self.call(arguments:, request_context:)
limit = arguments.fetch("limit", 50).to_i.clamp(1, 100)
events =
diff --git a/plugins/discourse-events/plugin.rb b/plugins/discourse-events/plugin.rb
index 4fdafc85b0b..3ba561ea16d 100644
--- a/plugins/discourse-events/plugin.rb
+++ b/plugins/discourse-events/plugin.rb
@@ -1088,6 +1088,7 @@ after_initialize do
},
additionalProperties: false,
},
+ output_schema: DiscourseEvents::McpTools::ListEvents::OUTPUT_SCHEMA,
required_scopes: %w[discourse-calendar:read],
annotations: {
readOnlyHint: true,
diff --git a/plugins/discourse-reactions/lib/discourse_reactions/mcp_tools.rb b/plugins/discourse-reactions/lib/discourse_reactions/mcp_tools.rb
index ae2e84d25e8..3ea2a7a6ea9 100644
--- a/plugins/discourse-reactions/lib/discourse_reactions/mcp_tools.rb
+++ b/plugins/discourse-reactions/lib/discourse_reactions/mcp_tools.rb
@@ -3,6 +3,12 @@
module DiscourseReactions
module McpTools
class SetReaction
+ OUTPUT_SCHEMA =
+ DiscourseMcp::OutputSchema.object(
+ post_id: DiscourseMcp::OutputSchema::INTEGER,
+ reaction: DiscourseMcp::OutputSchema::STRING,
+ )
+
def self.call(arguments:, request_context:)
post = Post.find_by(id: arguments.fetch("post_id"))
if post.blank? || !request_context.guardian.can_see?(post)
diff --git a/plugins/discourse-reactions/plugin.rb b/plugins/discourse-reactions/plugin.rb
index 17767aa88c1..5d92a38ce4d 100644
--- a/plugins/discourse-reactions/plugin.rb
+++ b/plugins/discourse-reactions/plugin.rb
@@ -458,6 +458,7 @@ after_initialize do
required: %w[post_id reaction],
additionalProperties: false,
},
+ output_schema: DiscourseReactions::McpTools::SetReaction::OUTPUT_SCHEMA,
required_scopes: %w[discourse-reactions:write],
annotations: {
readOnlyHint: false,
diff --git a/plugins/discourse-solved/lib/discourse_solved/mcp_tools.rb b/plugins/discourse-solved/lib/discourse_solved/mcp_tools.rb
index 5d39d07aa00..fe32aa062d7 100644
--- a/plugins/discourse-solved/lib/discourse_solved/mcp_tools.rb
+++ b/plugins/discourse-solved/lib/discourse_solved/mcp_tools.rb
@@ -3,6 +3,12 @@
module DiscourseSolved
module McpTools
class SetSolution
+ OUTPUT_SCHEMA =
+ DiscourseMcp::OutputSchema.object(
+ post_id: DiscourseMcp::OutputSchema::INTEGER,
+ accepted: DiscourseMcp::OutputSchema::BOOLEAN,
+ )
+
def self.call(arguments:, request_context:)
service =
(
diff --git a/plugins/discourse-solved/plugin.rb b/plugins/discourse-solved/plugin.rb
index 2031047915e..8810a5e6553 100644
--- a/plugins/discourse-solved/plugin.rb
+++ b/plugins/discourse-solved/plugin.rb
@@ -505,6 +505,7 @@ after_initialize do
required: %w[post_id accepted],
additionalProperties: false,
},
+ output_schema: DiscourseSolved::McpTools::SetSolution::OUTPUT_SCHEMA,
required_scopes: %w[discourse-solved:write],
annotations: {
readOnlyHint: false,
diff --git a/plugins/discourse-topic-voting/lib/discourse_topic_voting/mcp_tools.rb b/plugins/discourse-topic-voting/lib/discourse_topic_voting/mcp_tools.rb
index dafd503a1b3..ded92ed3971 100644
--- a/plugins/discourse-topic-voting/lib/discourse_topic_voting/mcp_tools.rb
+++ b/plugins/discourse-topic-voting/lib/discourse_topic_voting/mcp_tools.rb
@@ -3,6 +3,12 @@
module DiscourseTopicVoting
module McpTools
class SetVote
+ OUTPUT_SCHEMA =
+ DiscourseMcp::OutputSchema.object(
+ topic_id: DiscourseMcp::OutputSchema::INTEGER,
+ voted: DiscourseMcp::OutputSchema::BOOLEAN,
+ )
+
def self.call(arguments:, request_context:)
service =
(
diff --git a/plugins/discourse-topic-voting/plugin.rb b/plugins/discourse-topic-voting/plugin.rb
index 3c2ca21fca2..6b34883afab 100755
--- a/plugins/discourse-topic-voting/plugin.rb
+++ b/plugins/discourse-topic-voting/plugin.rb
@@ -275,6 +275,7 @@ after_initialize do
required: %w[topic_id voted],
additionalProperties: false,
},
+ output_schema: DiscourseTopicVoting::McpTools::SetVote::OUTPUT_SCHEMA,
required_scopes: %w[discourse-topic-voting:write],
annotations: {
readOnlyHint: false,
diff --git a/spec/lib/discourse_mcp/regular_user_tools_spec.rb b/spec/lib/discourse_mcp/regular_user_tools_spec.rb
index 1e939a9ea19..38acc5eebd5 100644
--- a/spec/lib/discourse_mcp/regular_user_tools_spec.rb
+++ b/spec/lib/discourse_mcp/regular_user_tools_spec.rb
@@ -751,6 +751,13 @@ describe DiscourseMcp::Tools do
end
describe DiscourseMcp::CorePrimitives do
+ it "declares an output schema for every tool" do
+ tools_without_output_schema =
+ DiscourseMcp.registry.all(:tool).reject(&:output_schema).map(&:identifier)
+
+ expect(tools_without_output_schema).to be_empty
+ end
+
it "registers the compatible regular-user tool names" do
expected_names = %w[
discourse_create_post
diff --git a/spec/requests/mcp_controller_spec.rb b/spec/requests/mcp_controller_spec.rb
index 553eb222c6f..445a7c0bf12 100644
--- a/spec/requests/mcp_controller_spec.rb
+++ b/spec/requests/mcp_controller_spec.rb
@@ -200,9 +200,11 @@ describe "MCP transport" do
post "/mcp", params: list_request.to_json, headers: classic_headers
- tool_names = response.parsed_body.dig("result", "tools").pluck("name")
+ tools = response.parsed_body.dig("result", "tools")
+ tool_names = tools.pluck("name")
expect(tool_names).to include("discourse_current_user_get")
expect(tool_names).to all(match(/\A[A-Za-z0-9_]+\z/))
+ expect(tools).to all(include("outputSchema" => include("type" => "object")))
end
it "uses the server-wide cache TTL setting for cacheable responses" do