rails-pg-extras-mcp 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2b38c7170279b40f497842e8b52683e94ec21ed567f9081ca4e0041fac00cc0
+  data.tar.gz: d099ef809db25a1cadacc15faea3fc6bc7ba49dc8e60f985f7e1835ce962e127
+SHA512:
+  metadata.gz: c4fd58adbed92be275183094e26afb12ef156a214170f55c5e3e563d39e2fabdf59b4c7676401f97b820346e5173feef8630d41343d48d4d086961ece3dd4c93
+  data.tar.gz: f8365a1506c36a6c9475bddadce4d97a0651b4a20e5a05100020ccfb49730f0691407e805503bc462403e24de9a800ad072984dfc8f452797cd11c560ae1a9c9

data/.gitattributes

@@ -0,0 +1,2 @@
+assets/* linguist-vendored
+

data/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: Ruby CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['3.4', '3.3', '3.2', '3.1']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+      - name: Setup dependencies
+        run: |
+          gem install bundler -v 2.4.22
+          sudo apt-get update --allow-releaseinfo-change
+          sudo apt install postgresql-client
+          sudo apt install libpq-dev
+          bundle config set --local path 'vendor/bundle'
+          bundle install
+          sleep 10
+      - name: Run tests
+        run: |
+          bundle exec rspec spec/
+

data/.gitignore

@@ -0,0 +1,7 @@
+Gemfile.lock
+.ruby-version
+pkg/
+*.gem
+docker-compose.yml
+.byebug_history
+

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright © Paweł Urbanek 2025
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# 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. 
+
+A tool for those adventurous enough to connect LLMs directly to the database.
+
+## Installation
+
+```bash
+bundle add rails-pg-extras
+bundle add rails-pg-extras-mcp
+```
+
+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"
+```
+
+Install [mcp-remote](https://github.com/geelen/mcp-remote):
+
+```bash
+npm install -g mcp-remote
+```
+
+and in your LLM of choice:
+
+```json
+{
+  "mcpServers": {
+    "pg-extras": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "http://localhost:3000/pg-extras-mcp/sse"
+      ]
+    }
+  }
+}
+```
+
+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)
+
+## Status
+
+Project is in an early beta, so proceed with caution.

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+require "rack"
+require "ruby-pg-extras"
+require "rails-pg-extras"
+
+SKIP_QUERIES = %i[
+  add_extensions
+  pg_stat_statements_reset
+  kill_pid
+  kill_all
+  mandelbrot
+]
+
+QUERY_TOOL_CLASSES = RubyPgExtras::QUERIES.reject { |q| SKIP_QUERIES.include?(q) }.map do |query_name|
+  Class.new(FastMcp::Tool) do
+    description RubyPgExtras.description_for(query_name: query_name)
+
+    define_method :call do
+      RailsPgExtras.public_send(query_name, in_format: :hash)
+    end
+
+    define_singleton_method :name do
+      query_name.to_s
+    end
+  end
+end
+
+class MissingFkConstraintsTool < FastMcp::Tool
+  description "Shows missing foreign key constraints"
+
+  def call
+    RailsPgExtras.missing_fk_constraints(in_format: :hash)
+  end
+
+  def self.name
+    "missing_fk_constraints"
+  end
+end
+
+class MissingFkIndexesTool < FastMcp::Tool
+  description "Shows missing foreign key indexes"
+
+  def call
+    RailsPgExtras.missing_fk_indexes(in_format: :hash)
+  end
+
+  def self.name
+    "missing_fk_indexes"
+  end
+end
+
+class DiagnoseTool < FastMcp::Tool
+  description "Performs a health check of the database"
+
+  def call
+    RailsPgExtras.diagnose(in_format: :hash)
+  end
+
+  def self.name
+    "diagnose"
+  end
+end
+
+class ReadmeResource < FastMcp::Resource
+  uri "https://raw.githubusercontent.com/pawurb/rails-pg-extras/refs/heads/main/README.md"
+  resource_name "README"
+  description "The README for RailsPgExtras"
+  mime_type "text/plain"
+
+  def content
+    File.read(uri)
+  end
+end
+
+module RailsPgExtrasMcp
+  class App
+    def self.build
+      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,
+        path_prefix: "/pg-extras-mcp",
+        logger: Logger.new($stdout),
+      ) do |server|
+        server.register_tools(DiagnoseTool)
+        server.register_tools(MissingFkConstraintsTool)
+        server.register_tools(MissingFkIndexesTool)
+        server.register_tools(*QUERY_TOOL_CLASSES)
+
+        server.register_resource(ReadmeResource)
+
+        Rack::Builder.new { run mcp_app }
+      end
+    end
+  end
+end

data/lib/rails_pg_extras_mcp/version.rb

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

data/rails-pg-extras-mcp.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "rails_pg_extras_mcp/version"
+
+Gem::Specification.new do |s|
+  s.name = "rails-pg-extras-mcp"
+  s.version = RailsPgExtrasMcp::VERSION
+  s.authors = ["pawurb"]
+  s.email = ["contact@pawelurbanek.com"]
+  s.summary = %q{ MCP interface for rails-pg-extras }
+  s.description = %q{ MCP interface for rails-pg-extras. It enables LLMs to analyze the PostgreSQL metadata and performance metrics. }
+  s.homepage = "http://github.com/pawurb/rails-pg-extras-mcp"
+  s.files = `git ls-files`.split("\n")
+  s.test_files = s.files.grep(%r{^(spec)/})
+  s.require_paths = ["lib"]
+  s.license = "MIT"
+  s.add_dependency "rails-pg-extras", "~> 5.6"
+  s.add_dependency "rails"
+  s.add_dependency "fast-mcp"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "rufo"
+
+  if s.respond_to?(:metadata=)
+    s.metadata = { "rubygems_mfa_required" => "true" }
+  end
+end

data/spec/smoke_spec.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+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
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler/setup"
+require_relative "../lib/rails-pg-extras-mcp"

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification
+name: rails-pg-extras-mcp
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- pawurb
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-06-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails-pg-extras
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.6'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fast-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rufo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: " MCP interface for rails-pg-extras. It enables LLMs to analyze the PostgreSQL
+  metadata and performance metrics. "
+email:
+- contact@pawelurbanek.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitattributes"
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- 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
+homepage: http://github.com/pawurb/rails-pg-extras-mcp
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: MCP interface for rails-pg-extras
+test_files:
+- spec/smoke_spec.rb
+- spec/spec_helper.rb