rails-pg-extras-mcp 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2b38c7170279b40f497842e8b52683e94ec21ed567f9081ca4e0041fac00cc0
-  data.tar.gz: d099ef809db25a1cadacc15faea3fc6bc7ba49dc8e60f985f7e1835ce962e127
+  metadata.gz: 4b1051245810be2fecf8e867a4d310f92afb59428b99946191a1e206cf5b44a0
+  data.tar.gz: 36da9617db4420bdc098e9562ddd5ae521b57b08bea97737a079cf1cae0e31c8
 SHA512:
-  metadata.gz: c4fd58adbed92be275183094e26afb12ef156a214170f55c5e3e563d39e2fabdf59b4c7676401f97b820346e5173feef8630d41343d48d4d086961ece3dd4c93
-  data.tar.gz: f8365a1506c36a6c9475bddadce4d97a0651b4a20e5a05100020ccfb49730f0691407e805503bc462403e24de9a800ad072984dfc8f452797cd11c560ae1a9c9
+  metadata.gz: 16765fe32563b12c1a8b2d7136c8f4a32556caafc52d223060c7af000b71fc747329e1e4a7296aafb73ba218b9aa57ae5a72aedcad1ebc68bc3ed9a03cbb5146
+  data.tar.gz: 2d0c7c8f2cb2317d02621752f6d82cadfd6c7ed82b364529bf15a6f5cf37c9f1f54ef7e13316139db8173a7f09562086afa626643d4cb6f5e4aca28be005b1f7

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,15 +11,20 @@ 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`
 
 ```ruby
-# Authentication is not yet supported
 mount RailsPgExtras.mcp_app, at: "pg-extras-mcp"
 ```
 
+with optional authorization:
+
+```ruby
+mount RailsPgExtras.mcp_app(auth_token: "secret"), at: "pg-extras-mcp"
+```
+
 Install [mcp-remote](https://github.com/geelen/mcp-remote):
 
 ```bash
@@ -36,7 +40,9 @@ and in your LLM of choice:
       "command": "npx",
       "args": [
         "mcp-remote",
-        "http://localhost:3000/pg-extras-mcp/sse"
+        "http://localhost:3000/pg-extras-mcp/sse",
+        "--header",
+        "Authorization: secret"
       ]
     }
   }
@@ -45,8 +51,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,68 @@ 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:)
+    if query.downcase.include?("analyze")
+      raise "This query is not allowed. It contains a denied ANALYZE keyword."
+    end
+
+    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"
@@ -76,23 +138,35 @@ end
 
 module RailsPgExtrasMcp
   class App
-    def self.build
+    def self.build(auth_token: nil)
       app = lambda do |_env|
         [200, { "Content-Type" => "text/html" },
          ["<html><body><h1>Hello from Rack!</h1><p>This is a simple Rack app with MCP middleware.</p></body></html>"]]
       end
 
-      # Create the MCP middleware
-      mcp_app = FastMcp.rack_middleware(
-        app,
-        name: "rails-pg-extras-mcp", version: RailsPgExtrasMcp::VERSION,
+      opts = {
+        name: "rails-pg-extras-mcp",
+        version: RailsPgExtrasMcp::VERSION,
         path_prefix: "/pg-extras-mcp",
         logger: Logger.new($stdout),
-      ) do |server|
+      }
+
+      if auth_token.present?
+        opts[:auth_token] = auth_token
+      end
+
+      rack_method_name = auth_token.present? ? :authenticated_rack_middleware : :rack_middleware
+
+      # Create the MCP middleware
+      mcp_app = FastMcp.public_send(rack_method_name,
+                                    app,
+                                    **opts) do |server|
         server.register_tools(DiagnoseTool)
         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.1"
 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.1
 platform: ruby
 authors:
 - pawurb
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-12 00:00:00.000000000 Z
+date: 2025-06-23 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