rails-pg-extras-mcp 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2b38c7170279b40f497842e8b52683e94ec21ed567f9081ca4e0041fac00cc0
-  data.tar.gz: d099ef809db25a1cadacc15faea3fc6bc7ba49dc8e60f985f7e1835ce962e127
+  metadata.gz: e8d771e114f631fe7a9708fca02ae9466ab30a3da437ad14bf2085ec3a723592
+  data.tar.gz: e96491dbe241a9bb66484e8bc9088cdb1d933f09ae62a1d89d9b65b44e5ebad5
 SHA512:
-  metadata.gz: c4fd58adbed92be275183094e26afb12ef156a214170f55c5e3e563d39e2fabdf59b4c7676401f97b820346e5173feef8630d41343d48d4d086961ece3dd4c93
-  data.tar.gz: f8365a1506c36a6c9475bddadce4d97a0651b4a20e5a05100020ccfb49730f0691407e805503bc462403e24de9a800ad072984dfc8f452797cd11c560ae1a9c9
+  metadata.gz: 9aefce0884fb505759dcaafbadbfdbcf821826400273c74f20a1a5d8a69cc41e81d4130789f5b07f36cb5b526e75c2c6b01ac6356562f78233769de582403221
+  data.tar.gz: 0ec7f68987e6ee2e358745827d060e2723f9f68c53cdf2232b051ad6d723d8f873e325acbe52a1e46d2c0e6df9945a376abecab2dd93a75666045e4f57763891

data/README.md

@@ -1,9 +1,8 @@
 # Rails PG Extras MCP [![Gem Version](https://badge.fury.io/rb/rails-pg-extras-mcp.svg)](https://badge.fury.io/rb/rails-pg-extras-mcp) [![GH Actions](https://github.com/pawurb/rails-pg-extras-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pawurb/rails-pg-extras-mcp/actions)
 
+MCP ([Model Context Protocol](https://modelcontextprotocol.io/introduction)) interface for [rails-pg-extras](https://github.com/pawurb/rails-pg-extras) gem. It enables PostgreSQL metadata and performance analysis with a simple LLM prompt.  
 
-MCP ([Model Context Protocol](https://modelcontextprotocol.io/introduction)) interface for [rails-pg-extras](https://github.com/pawurb/rails-pg-extras) gem. 
-
-A tool for those adventurous enough to connect LLMs directly to the database.
+![LLM interface](https://github.com/pawurb/rails-pg-extras/raw/main/pg-extras-mcp.png)
 
 ## Installation
 
@@ -12,7 +11,7 @@ bundle add rails-pg-extras
 bundle add rails-pg-extras-mcp
 ```
 
-Library supports MCP protocol via HTTP SSE interface. 
+The library supports MCP protocol via HTTP SSE interface. 
 
 `config/routes.rb`
 
@@ -45,8 +44,17 @@ and in your LLM of choice:
 
 You can now ask LLM questions about the metadata and performance metrics of your database.
 
-![LLM interface](https://github.com/pawurb/rails-pg-extras/raw/main/pg-extras-mcp.png)
+## Optional EXPLAIN ANALYZE support
+
+[`calls`](https://github.com/pawurb/rails-pg-extras?tab=readme-ov-file#calls) and [`outliers`](https://github.com/pawurb/rails-pg-extras?tab=readme-ov-file#outliers) methods return a list of bottleneck queries. LLM can get better insights into these queries by performing `EXPLAIN` and `EXPLAIN ANALYZE` analysis. MCP server exposes two optional methods for this purpose: `explain` and `explain_analyze`. 
+
+You can enable them by setting the following `ENV` variables:
+
+`ENV['PG_EXTRAS_MCP_EXPLAIN_ENABLED'] = 'true'`
+`ENV['PG_EXTRAS_MCP_EXPLAIN_ANALYZE_ENABLED'] = 'true'`
+
+Enabling these features means that an LLM, can run arbitrary queries in your database. The execution context is wrapped in a transaction and rolled back, so, in theory, any data modification should not be possible. But it's advised to configure a read-only permission if you want to use these features. By specifying `ENV['RAILS_PG_EXTRAS_DATABASE_URL']` you can overwrite the default Rails ActiveRecord database connection to restrict an access scope.
 
 ## Status
 
-Project is in an early beta, so proceed with caution.
+The project is in an early beta, so proceed with caution.

data/Rakefile

@@ -2,4 +2,3 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
-

data/lib/rails-pg-extras-mcp.rb

@@ -63,6 +63,63 @@ class DiagnoseTool < FastMcp::Tool
   end
 end
 
+class ExplainBaseTool < FastMcp::Tool
+  DENYLIST = %w[
+    delete,
+    insert,
+    update,
+    truncate,
+    drop,
+    alter,
+    create,
+    grant,
+    begin,
+    commit,
+  ]
+
+  arguments do
+    required(:query).filled(:string).description("The query to debug")
+  end
+
+  def call(query:)
+    connection = RailsPgExtras.connection
+
+    if DENYLIST.any? { |deny| query.downcase.include?(deny) }
+      raise "This query is not allowed. It contains a denied keyword. Denylist: #{DENYLIST.join(", ")}"
+    end
+
+    connection.execute("BEGIN")
+    result = connection.execute("#{query}")
+    connection.execute("ROLLBACK")
+
+    result.to_a
+  end
+end
+
+class ExplainTool < ExplainBaseTool
+  description "EXPLAIN a query. It must be an SQL string, without the EXPLAIN prefix"
+
+  def self.name
+    "explain_analyze"
+  end
+
+  def call(query:)
+    super(query: "EXPLAIN #{query}")
+  end
+end
+
+class ExplainAnalyzeTool < ExplainBaseTool
+  description "EXPLAIN ANALYZE a query. It must be an SQL string, without the EXPLAIN ANALYZE prefix"
+
+  def self.name
+    "explain_analyze"
+  end
+
+  def call(query:)
+    super(query: "EXPLAIN ANALYZE #{query}")
+  end
+end
+
 class ReadmeResource < FastMcp::Resource
   uri "https://raw.githubusercontent.com/pawurb/rails-pg-extras/refs/heads/main/README.md"
   resource_name "README"
@@ -93,6 +150,8 @@ module RailsPgExtrasMcp
         server.register_tools(MissingFkConstraintsTool)
         server.register_tools(MissingFkIndexesTool)
         server.register_tools(*QUERY_TOOL_CLASSES)
+        server.register_tools(ExplainTool) if ENV["PG_EXTRAS_MCP_EXPLAIN_ENABLED"] == "true"
+        server.register_tools(ExplainAnalyzeTool) if ENV["PG_EXTRAS_MCP_EXPLAIN_ANALYZE_ENABLED"] == "true"
 
         server.register_resource(ReadmeResource)
 

data/lib/rails_pg_extras_mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsPgExtrasMcp
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/spec/smoke_spec.rb

@@ -3,67 +3,10 @@
 require "spec_helper"
 require "rails-pg-extras"
 
-describe RailsPgExtras do
-  SKIP_QUERIES = %i[
-    kill_all
-    table_schema
-    table_foreign_keys
-  ]
-
-  RailsPgExtras::QUERIES.reject { |q| SKIP_QUERIES.include?(q) }.each do |query_name|
-    it "#{query_name} query can be executed" do
-      expect do
-        RailsPgExtras.run_query(
-          query_name: query_name,
-          in_format: :hash,
-        )
-      end.not_to raise_error
-    end
-  end
-
-  it "runs the custom methods" do
-    expect do
-      RailsPgExtras.diagnose(in_format: :hash)
-    end.not_to raise_error
-
-    expect do
-      RailsPgExtras.index_info(in_format: :hash)
-    end.not_to raise_error
-
-    expect do
-      RailsPgExtras.table_info(in_format: :hash)
-    end.not_to raise_error
-  end
-
-  it "collecting queries data works" do
-    output = RailsPgExtras.measure_queries { RailsPgExtras.diagnose(in_format: :hash) }
-    expect(output.fetch(:count) > 0).to eq(true)
-  end
-
-  it "supports custom RAILS_PG_EXTRAS_DATABASE_URL" do
-    ENV["RAILS_PG_EXTRAS_DATABASE_URL"] = ENV["DATABASE_URL"]
-    puts ENV["RAILS_PG_EXTRAS_DATABASE_URL"]
-
-    expect do
-      RailsPgExtras.calls
-    end.not_to raise_error
-
-    ENV["RAILS_PG_EXTRAS_DATABASE_URL"] = nil
-  end
-
-  describe "missing_fk_indexes" do
-    it "works" do
-      expect {
-        RailsPgExtras.missing_fk_indexes
-      }.not_to raise_error
-    end
-  end
-
-  describe "missing_fk_constraints" do
-    it "works" do
-      expect {
-        RailsPgExtras.missing_fk_constraints
-      }.not_to raise_error
-    end
+describe RailsPgExtrasMcp do
+  it "works" do
+    expect {
+      RailsPgExtrasMcp::App.build
+    }.not_to raise_error
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-pg-extras-mcp
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - pawurb
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-12 00:00:00.000000000 Z
+date: 2025-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails-pg-extras
@@ -112,7 +112,6 @@ files:
 - lib/rails-pg-extras-mcp.rb
 - lib/rails_pg_extras_mcp/version.rb
 - pg-extras-mcp.png
-- rails-pg-extras-diagnose.png
 - rails-pg-extras-mcp.gemspec
 - spec/smoke_spec.rb
 - spec/spec_helper.rb