A platform for community discussion. Free, open, simple.
FEATURE: Add Data Explorer query tools to the MCP server (#44111)
Natalie Tay25bafa201b3b
diff --git a/lib/discourse_mcp/server.rb b/lib/discourse_mcp/server.rbindex 7d8f3f7ef54..69da122ff6d 100644--- a/lib/discourse_mcp/server.rb+++ b/lib/discourse_mcp/server.rb@@ -46,6 +46,8 @@ module DiscourseMcprescue Discourse::InvalidAccesserror = Error.new("Not authorized", code: -32_001, http_status: 403)Response.new(http_status: 403, body: failure(payload&.dig("id"), error), headers: {})+ rescue RateLimiter::LimitExceeded+ raiserescue JSONSchemer::InvalidSchema => errorprotocol_error = Error.new("Invalid schema", code: -32_000, http_status: 500)Discourse.warn_exception(error, message: "MCP schema validation failed")diff --git a/plugins/discourse-data-explorer/app/controllers/discourse_data_explorer/query_controller.rb b/plugins/discourse-data-explorer/app/controllers/discourse_data_explorer/query_controller.rbindex ca8211b3d7f..38da7e72416 100644--- a/plugins/discourse-data-explorer/app/controllers/discourse_data_explorer/query_controller.rb+++ b/plugins/discourse-data-explorer/app/controllers/discourse_data_explorer/query_controller.rb@@ -301,17 +301,7 @@ module DiscourseDataExplorerdef rate_limit_query_runs!return if !is_api? && !is_user_api?- RateLimiter.new(- nil,- "api-query-run-10-sec",- GlobalSetting.max_data_explorer_api_reqs_per_10_seconds,- 10.seconds,- ).performed!- rescue RateLimiter::LimitExceeded => e- if GlobalSetting.max_data_explorer_api_req_mode.include?("warn")- Discourse.warn("Query run 10 second rate limit exceeded", query_id: params[:id])- end- raise e if GlobalSetting.max_data_explorer_api_req_mode.include?("block")+ QueryRunRateLimiter.perform!(query_id: params[:id])enddef run_download(query, explain:)@@ -361,15 +351,7 @@ module DiscourseDataExplorerenddef format_query_error(err)- err_class = err.class- err_msg = err.message- if err.is_a?(ActiveRecord::StatementInvalid)- err_class = err.original_exception.class- err_msg.gsub!("#{err_class}:", "")- else- err_msg = "#{err_class}: #{err_msg}"- end- { success: false, errors: [err_msg] }+ { success: false, errors: [QueryErrorFormatter.message(err)] }enddef render_invalid_json_paramsdiff --git a/plugins/discourse-data-explorer/config/locales/server.en.yml b/plugins/discourse-data-explorer/config/locales/server.en.ymlindex ebb602311ca..89e7dc89691 100644--- a/plugins/discourse-data-explorer/config/locales/server.en.yml+++ b/plugins/discourse-data-explorer/config/locales/server.en.yml@@ -21,6 +21,9 @@ en:run_sql: "Ran SQL query"submit_query: "Submitted generated query %{name}"discourse_data_explorer:+ mcp:+ query_failed: "The query could not be run: %{message}"+ query_not_found: "Query not found"ai:error_agent_not_configured: "AI agent is not configured. Please check the AI features settings."error_no_sql_returned: "AI did not return a valid SQL query. Please try again or write the query manually."diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/mcp_tools.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/mcp_tools.rbnew file mode 100644index 00000000000..bbfa8d65f6b--- /dev/null+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/mcp_tools.rb@@ -0,0 +1,141 @@+# frozen_string_literal: true++module DiscourseDataExplorer+ module McpTools+ READ_SCOPE = "mcp:data-explorer:read"++ module Support+ module_function++ def query!(id, guardian:, admin: false)+ guardian.ensure_is_admin! if admin++ query = Query.find(id)+ if query.hidden || (!admin && !guardian.user_can_access_query?(query))+ raise DiscourseMcp::ToolError, I18n.t("discourse_data_explorer.mcp.query_not_found")+ end++ query+ rescue ActiveRecord::RecordNotFound+ raise DiscourseMcp::ToolError, I18n.t("discourse_data_explorer.mcp.query_not_found")+ end++ def parameter_json(parameter)+ {+ identifier: parameter.identifier,+ type: parameter.type.to_s,+ default: parameter.default&.to_s,+ nullable: parameter.nullable,+ }+ end++ def limit(value)+ return SiteSetting.data_explorer_query_result_limit if value.nil?+ return QUERY_RESULT_MAX_LIMIT if value == "ALL"++ value+ end+ end++ class GetQuery+ REQUIRED_SCOPES = [READ_SCOPE].freeze+ PARAMETER_SCHEMA =+ DiscourseMcp::OutputSchema.object(+ identifier: DiscourseMcp::OutputSchema::STRING,+ type: DiscourseMcp::OutputSchema::STRING,+ default: DiscourseMcp::OutputSchema::STRING_OR_NULL,+ nullable: DiscourseMcp::OutputSchema::BOOLEAN,+ )+ OUTPUT_SCHEMA =+ DiscourseMcp::OutputSchema.object(+ id: DiscourseMcp::OutputSchema::INTEGER,+ name: DiscourseMcp::OutputSchema::STRING,+ description: DiscourseMcp::OutputSchema::STRING_OR_NULL,+ username: DiscourseMcp::OutputSchema::STRING_OR_NULL,+ group_ids: {+ type: "array",+ items: DiscourseMcp::OutputSchema::INTEGER,+ },+ last_run_at: DiscourseMcp::OutputSchema::STRING_OR_NULL,+ sql: DiscourseMcp::OutputSchema::STRING,+ param_info: {+ type: "array",+ items: PARAMETER_SCHEMA,+ },+ )++ def self.call(arguments:, request_context:)+ query =+ Support.query!(arguments.fetch("id"), guardian: request_context.guardian, admin: true)++ DiscourseMcp::ToolHelpers.text_and_structured(+ id: query.id,+ name: query.name,+ description: query.description,+ username: query.user&.username,+ group_ids: query.groups.map(&:id),+ last_run_at: query.last_run_at&.iso8601,+ sql: query.sql,+ param_info:+ query.params.uniq(&:identifier).map { |parameter| Support.parameter_json(parameter) },+ )+ end+ end++ class RunQuery+ REQUIRED_SCOPES = [READ_SCOPE].freeze+ OUTPUT_SCHEMA =+ DiscourseMcp::OutputSchema.object(+ optional: %w[explain relations],+ columns: DiscourseMcp::OutputSchema::STRING_ARRAY,+ rows: {+ type: "array",+ items: {+ type: "array",+ items: DiscourseMcp::OutputSchema::ANY,+ },+ },+ result_count: DiscourseMcp::OutputSchema::INTEGER,+ duration_ms: {+ type: "number",+ },+ explain: DiscourseMcp::OutputSchema::STRING,+ relations: DiscourseMcp::OutputSchema::OBJECT,+ )++ def self.call(arguments:, request_context:)+ query = Support.query!(arguments.fetch("id"), guardian: request_context.guardian)+ QueryRunRateLimiter.perform!(query_id: query.id)+ query.record_run!++ result =+ QueryRunner.run(+ query,+ arguments["params"],+ current_user: request_context.user,+ explain: arguments.fetch("explain", false),+ limit: Support.limit(arguments["limit"]),+ )++ if result[:error]+ raise DiscourseMcp::ToolError,+ I18n.t(+ "discourse_data_explorer.mcp.query_failed",+ message: QueryErrorFormatter.message(result[:error]),+ )+ end++ output = {+ columns: result[:columns],+ rows: result[:rows],+ result_count: result[:result_count],+ duration_ms: result[:duration],+ }+ output[:explain] = result[:explain] if result[:explain]+ output[:relations] = result[:relations] if result[:relations].present?++ DiscourseMcp::ToolHelpers.text_and_structured(output)+ end+ end+ end+enddiff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_error_formatter.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_error_formatter.rbnew file mode 100644index 00000000000..2d18bc2c515--- /dev/null+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_error_formatter.rb@@ -0,0 +1,12 @@+# frozen_string_literal: true++module DiscourseDataExplorer+ class QueryErrorFormatter+ def self.message(error)+ return "#{error.class}: #{error.message}" unless error.is_a?(ActiveRecord::StatementInvalid)++ database_error_class = error.cause&.class || error.class+ error.message.delete_prefix("#{database_error_class}:").strip+ end+ end+enddiff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_run_rate_limiter.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_run_rate_limiter.rbnew file mode 100644index 00000000000..38ddfacab7d--- /dev/null+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_run_rate_limiter.rb@@ -0,0 +1,19 @@+# frozen_string_literal: true++module DiscourseDataExplorer+ class QueryRunRateLimiter+ def self.perform!(query_id:)+ RateLimiter.new(+ nil,+ "api-query-run-10-sec",+ GlobalSetting.max_data_explorer_api_reqs_per_10_seconds,+ 10.seconds,+ ).performed!+ rescue RateLimiter::LimitExceeded => error+ if GlobalSetting.max_data_explorer_api_req_mode.include?("warn")+ Discourse.warn("Query run 10 second rate limit exceeded", query_id:)+ end+ raise error if GlobalSetting.max_data_explorer_api_req_mode.include?("block")+ end+ end+enddiff --git a/plugins/discourse-data-explorer/plugin.rb b/plugins/discourse-data-explorer/plugin.rbindex 8a7f7fdeac1..07aa3edd0ce 100644--- a/plugins/discourse-data-explorer/plugin.rb+++ b/plugins/discourse-data-explorer/plugin.rb@@ -33,6 +33,76 @@ endrequire_relative "lib/discourse_data_explorer/engine"after_initialize do+ require_relative "lib/discourse_data_explorer/mcp_tools"++ register_mcp_tool(+ "discourse_get_query",+ title: "Get Data Explorer query",+ description:+ "Returns the definition of a saved Data Explorer query. Requires an admin account.",+ implementation: DiscourseDataExplorer::McpTools::GetQuery,+ input_schema: {+ type: "object",+ properties: {+ id: {+ type: "integer",+ minimum: 1,+ },+ },+ required: ["id"],+ additionalProperties: false,+ },+ output_schema: DiscourseDataExplorer::McpTools::GetQuery::OUTPUT_SCHEMA,+ required_scopes: DiscourseDataExplorer::McpTools::GetQuery::REQUIRED_SCOPES,+ annotations: {+ readOnlyHint: true,+ destructiveHint: false,+ idempotentHint: true,+ openWorldHint: false,+ },+ risk: :administration,+ availability: -> { SiteSetting.data_explorer_enabled },+ )++ register_mcp_tool(+ "discourse_run_query",+ title: "Run Data Explorer query",+ description: "Runs a saved Data Explorer query that the authenticated user can access.",+ implementation: DiscourseDataExplorer::McpTools::RunQuery,+ input_schema: {+ type: "object",+ properties: {+ id: {+ type: "integer",+ },+ params: {+ type: "object",+ },+ limit: {+ anyOf: [+ { type: "integer", minimum: 1, maximum: DiscourseDataExplorer::QUERY_RESULT_MAX_LIMIT },+ { const: "ALL" },+ ],+ },+ explain: {+ type: "boolean",+ default: false,+ },+ },+ required: ["id"],+ additionalProperties: false,+ },+ output_schema: DiscourseDataExplorer::McpTools::RunQuery::OUTPUT_SCHEMA,+ required_scopes: DiscourseDataExplorer::McpTools::RunQuery::REQUIRED_SCOPES,+ annotations: {+ readOnlyHint: true,+ destructiveHint: false,+ idempotentHint: true,+ openWorldHint: false,+ },+ availability: -> { SiteSetting.data_explorer_enabled },+ )+GlobalSetting.add_default(:max_data_explorer_api_reqs_per_10_seconds, 2)# Available options:diff --git a/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/mcp_tools_spec.rb b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/mcp_tools_spec.rbnew file mode 100644index 00000000000..237f9fd4b62--- /dev/null+++ b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/mcp_tools_spec.rb@@ -0,0 +1,207 @@+# frozen_string_literal: true++describe DiscourseDataExplorer::McpTools::GetQuery do+ fab!(:admin)+ fab!(:moderator)+ fab!(:group)+ fab!(:query) do+ Fabricate(+ :query,+ user: admin,+ name: "Active members",+ description: "Lists active members",+ sql: "-- [params]\n-- int :minimum_id = 1\nSELECT :minimum_id::integer AS value",+ )+ end++ def request_context(user)+ instance_double(DiscourseMcp::RequestContext, user:, guardian: user.guardian)+ end++ before { SiteSetting.data_explorer_enabled = true }++ it "returns saved query details to an admin" do+ result =+ described_class.call(+ arguments: {+ "id" => query.id,+ },+ request_context: request_context(admin),+ ).fetch(:structuredContent)++ expect(result).to eq(+ id: query.id,+ name: "Active members",+ description: "Lists active members",+ username: admin.username,+ group_ids: [],+ last_run_at: nil,+ sql: query.sql,+ param_info: [{ identifier: "minimum_id", type: "int", default: "1", nullable: false }],+ )+ expect(+ JSONSchemer.schema(DiscourseDataExplorer::McpTools::GetQuery::OUTPUT_SCHEMA).valid?(+ JSON.parse(JSON.generate(result)),+ ),+ ).to eq(true)+ end++ it "does not expose SQL to a moderator who can run the query" do+ group.add(moderator)+ Fabricate(:query_group, query:, group:)++ expect do+ described_class.call(+ arguments: {+ "id" => query.id,+ },+ request_context: request_context(moderator),+ )+ end.to raise_error(Discourse::InvalidAccess)+ end++ it "does not expose hidden queries" do+ query.update!(hidden: true)++ expect do+ described_class.call(arguments: { "id" => query.id }, request_context: request_context(admin))+ end.to raise_error(+ DiscourseMcp::ToolError,+ I18n.t("discourse_data_explorer.mcp.query_not_found"),+ )+ end+end++describe DiscourseDataExplorer::McpTools::RunQuery do+ fab!(:admin)+ fab!(:moderator)+ fab!(:user)+ fab!(:group)+ fab!(:query) do+ Fabricate(+ :query,+ user: admin,+ sql: "-- [params]\n-- int :value = 1\nSELECT :value::integer AS value",+ )+ end++ def request_context(user)+ instance_double(DiscourseMcp::RequestContext, user:, guardian: user.guardian)+ end++ before do+ SiteSetting.data_explorer_enabled = true+ group.add(user)+ Fabricate(:query_group, query:, group:)+ end++ after { DiscourseDataExplorer::QueryRunner.invalidate(query.id) }++ it "runs an assigned query with parameters for a group member" do+ result =+ described_class.call(+ arguments: {+ "id" => query.id,+ "params" => {+ "value" => 42,+ },+ "limit" => 1,+ },+ request_context: request_context(user),+ ).fetch(:structuredContent)++ expect(result).to include(columns: ["value"], rows: [[42]], result_count: 1)+ expect(result[:duration_ms]).to be_a(Numeric)+ expect(result.keys).to contain_exactly(:columns, :rows, :result_count, :duration_ms)+ schema_errors =+ JSONSchemer+ .schema(DiscourseDataExplorer::McpTools::RunQuery::OUTPUT_SCHEMA)+ .validate(JSON.parse(JSON.generate(result)))+ .to_a+ expect(schema_errors).to be_empty+ expect(query.reload.last_run_at).to be_present+ end++ it "lets an admin run a query without a group assignment" do+ query.query_groups.delete_all++ result =+ described_class.call(+ arguments: {+ "id" => query.id,+ },+ request_context: request_context(admin),+ ).fetch(:structuredContent)++ expect(result).to include(columns: ["value"], rows: [[1]])+ end++ it "does not expose a query to a moderator without access" do+ expect do+ described_class.call(+ arguments: {+ "id" => query.id,+ },+ request_context: request_context(moderator),+ )+ end.to raise_error(+ DiscourseMcp::ToolError,+ I18n.t("discourse_data_explorer.mcp.query_not_found"),+ )+ end++ it "does not run a hidden query" do+ query.update!(hidden: true)++ expect do+ described_class.call(arguments: { "id" => query.id }, request_context: request_context(user))+ end.to raise_error(+ DiscourseMcp::ToolError,+ I18n.t("discourse_data_explorer.mcp.query_not_found"),+ )+ end++ it "reports query execution errors" do+ query.update!(sql: "SELECT * FROM a_table_that_does_not_exist")++ expect do+ described_class.call(arguments: { "id" => query.id }, request_context: request_context(user))+ end.to raise_error(DiscourseMcp::ToolError, /a_table_that_does_not_exist/)+ end+end++describe DiscourseDataExplorer::McpTools do+ before { SiteSetting.data_explorer_enabled = true }++ it "registers both tools with the dedicated read scope" do+ tools =+ %w[discourse_get_query discourse_run_query].index_with do |identifier|+ DiscourseMcp.registry.find(:tool, identifier)+ end++ expect(tools.transform_values(&:required_scopes)).to eq(+ "discourse_get_query" => [DiscourseDataExplorer::McpTools::READ_SCOPE],+ "discourse_run_query" => [DiscourseDataExplorer::McpTools::READ_SCOPE],+ )+ expect(tools.transform_values(&:output_schema).values).to all(be_present)+ expect(tools["discourse_get_query"].input_schema.dig("properties", "id", "minimum")).to eq(1)+ expect(tools["discourse_run_query"].input_schema.dig("properties", "id")).to eq(+ "type" => "integer",+ )+ expect(+ JSONSchemer.schema(tools["discourse_run_query"].input_schema).valid?(+ { "id" => -1, "limit" => "ALL" },+ ),+ ).to eq(true)+ end++ it "hides both tools when Data Explorer is disabled" do+ SiteSetting.data_explorer_enabled = false++ expect(+ %w[discourse_get_query discourse_run_query].map do |identifier|+ DiscourseMcp.registry.find(:tool, identifier).available?+ end,+ ).to all(eq(false))+ end+enddiff --git a/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/query_error_formatter_spec.rb b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/query_error_formatter_spec.rbnew file mode 100644index 00000000000..c5416169dc4--- /dev/null+++ b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/query_error_formatter_spec.rb@@ -0,0 +1,30 @@+# frozen_string_literal: true++describe DiscourseDataExplorer::QueryErrorFormatter do+ describe ".message" do+ it "includes the error class for query errors" do+ error = DiscourseDataExplorer::ValidationError.new("Invalid parameter")++ expect(described_class.message(error)).to eq(+ "DiscourseDataExplorer::ValidationError: Invalid parameter",+ )+ end++ it "uses the database error class for wrapped statement errors" do+ database_error = PG::UndefinedTable.new("relation does not exist")+ statement_error = nil++ begin+ raise database_error+ rescue PG::UndefinedTable+ begin+ raise ActiveRecord::StatementInvalid.new("PG::UndefinedTable: relation does not exist")+ rescue ActiveRecord::StatementInvalid => error+ statement_error = error+ end+ end++ expect(described_class.message(statement_error)).to eq("relation does not exist")+ end+ end+enddiff --git a/plugins/discourse-data-explorer/spec/requests/mcp_tools_spec.rb b/plugins/discourse-data-explorer/spec/requests/mcp_tools_spec.rbnew file mode 100644index 00000000000..817c5af156a--- /dev/null+++ b/plugins/discourse-data-explorer/spec/requests/mcp_tools_spec.rb@@ -0,0 +1,122 @@+# frozen_string_literal: true++describe "Data Explorer MCP tools" do+ fab!(:user) { Fabricate(:user, refresh_auto_groups: true) }+ fab!(:group)+ fab!(:other_group, :group)+ fab!(:query) { Fabricate(:query, sql: "SELECT 1::integer AS value") }++ before do+ SiteSetting.data_explorer_enabled = true+ SiteSetting.mcp_server_enabled = true+ group.add(user)+ Fabricate(:query_group, query:, group:)+ McpPrimitive.find_or_create_by!(kind: "tool", identifier: "discourse_run_query") do |primitive|+ primitive.enabled = true+ end+ end++ def authorize(*extra_scopes)+ scopes = [DiscourseMcp::INITIAL_SCOPE, *extra_scopes]+ scopes.each { |scope| McpGroupScope.create!(group:, scope:) }+ client =+ McpOauthClient.create!(+ client_id: SecureRandom.hex,+ name: "Data Explorer test client",+ registration_type: "pre_registered",+ trust_state: "approved",+ redirect_uris: ["http://127.0.0.1/callback"],+ )+ authorization =+ DiscourseMcp::OAuth::AuthorizationGrant.create!(+ user:,+ client:,+ redirect_uri: client.redirect_uris.first,+ requested_scopes: scopes,+ )+ @token = McpOauthAccessToken.issue!(authorization:)+ end++ def call_run_query+ post "/mcp",+ params: {+ jsonrpc: "2.0",+ id: 1,+ method: "tools/call",+ params: {+ name: "discourse_run_query",+ arguments: {+ id: query.id,+ },+ },+ }.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++ it "requires the Data Explorer read scope before running a query" do+ authorize++ call_run_query++ expect(response.status).to eq(403)+ expect(response.headers["WWW-Authenticate"]).to include(+ 'error="insufficient_scope"',+ 'scope="mcp:data-explorer:read"',+ )+ end++ it "runs an assigned query when the token has the Data Explorer read scope" do+ authorize(DiscourseDataExplorer::McpTools::READ_SCOPE)++ call_run_query++ expect(response.status).to eq(200)+ expect(response.parsed_body.dig("result", "structuredContent")).to include(+ "columns" => ["value"],+ "rows" => [[1]],+ )+ end++ it "does not run a query when the token has scope but the user lacks query access" do+ query.query_groups.delete_all+ Fabricate(:query_group, query:, group: other_group)+ authorize(DiscourseDataExplorer::McpTools::READ_SCOPE)++ call_run_query++ expect(response.status).to eq(200)+ expect(response.parsed_body.dig("result", "isError")).to eq(true)+ expect(response.parsed_body.dig("result", "content")).to eq(+ [{ "type" => "text", "text" => I18n.t("discourse_data_explorer.mcp.query_not_found") }],+ )+ end++ it "applies the Data Explorer API query rate limit" do+ SiteSetting.mcp_global_rate_limit_per_minute = 100+ global_setting :max_data_explorer_api_reqs_per_10_seconds, 1+ global_setting :max_data_explorer_api_req_mode, "block"+ RateLimiter.enable+ authorize(DiscourseDataExplorer::McpTools::READ_SCOPE)++ freeze_time+ call_run_query+ expect(response.status).to eq(200)++ call_run_query+ expect(response.status).to eq(429)+ expect(response.headers["Retry-After"]).to eq("10")+ expect(response.parsed_body).to eq(+ "jsonrpc" => "2.0",+ "id" => nil,+ "error" => {+ "code" => -32_000,+ "message" => "Rate limit exceeded",+ },+ )+ end+end