flehmen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e9d8368a8bcdfff9fca48d58621bf80fa261f0ca8a1999d668db8a96f707ece
+  data.tar.gz: 73121618744a5f85395c3b7eff399647e58625db1923245c40c88542fd4a4ab0
+SHA512:
+  metadata.gz: '01999308497ea1ab463e7347ee8f0c5ddb4ba8a7717ecc59925b010b81c8a898458ff5ed0d870532c831dc9d84c9836bb6e2cdb6f3d19fa4bb98d89fbb162ff8'
+  data.tar.gz: 95817db20d7b8d699b4b5ce42bf9c13e57fd75b847db0afdb95dbec40ba1f5100ee89b3e07fc4546d3ea7f3b6c4d3dec8ec4490f38ef939d61660d2370822802

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ryosk7
+
+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,211 @@
+# Flehmen
+
+<img width="410" height="410" alt="flehmen-response-cat" src="https://github.com/user-attachments/assets/07d5848a-d35f-4046-9530-69c855cfd07e" />
+
+A Ruby gem that exposes Rails ActiveRecord models to Claude Desktop via the Model Context Protocol (MCP). It auto-discovers models, provides read-only query tools, and filters sensitive fields.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "flehmen", github: "ryosk7/flehmen"
+```
+
+```bash
+bundle install
+```
+
+## Setup
+
+### Rails initializer
+
+Create `config/initializers/flehmen.rb`:
+
+```ruby
+Flehmen.configure do |config|
+  config.exclude_models = []
+  config.sensitive_fields = %i[
+    password_digest encrypted_password token secret
+    api_key api_secret access_token refresh_token
+    otp_secret reset_password_token encrypted_phone
+  ]
+  config.max_results = 100
+end
+
+Flehmen.mount_in_rails(Rails.application, path_prefix: "/mcp", localhost_only: false)
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "flehmen": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://localhost:3000/mcp/sse", "--allow-http"]
+    }
+  }
+}
+```
+
+> **Note:** The URL must end with `/mcp/sse`. The underlying `fast_mcp` gem uses SSE transport, so `/mcp` alone will return 404.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `models` | `:all` or `Array` | `:all` | Models to expose. `:all` auto-discovers all `ApplicationRecord` descendants |
+| `exclude_models` | `Array` | `[]` | Model classes or strings to exclude |
+| `sensitive_fields` | `Array<Symbol>` | See below | Fields masked with `[FILTERED]` across all models |
+| `model_sensitive_fields` | `Hash` | `{}` | Per-model sensitive fields |
+| `max_results` | `Integer` | `100` | Maximum records returned by any query |
+| `read_only_connection` | `Boolean` | `true` | Wraps all queries in `while_preventing_writes` to block accidental writes at the Rails level |
+
+### Default sensitive fields
+
+```ruby
+%i[
+  password_digest encrypted_password token secret
+  api_key api_secret access_token refresh_token
+  otp_secret reset_password_token confirmation_token
+  unlock_token remember_token authentication_token
+]
+```
+
+### Example
+
+```ruby
+Flehmen.configure do |config|
+  config.exclude_models = [AdminUser, "InternalLog"]
+  config.sensitive_fields += [:ssn, :credit_card_number]
+  config.model_sensitive_fields = {
+    "User" => [:phone_number, :address]
+  }
+  config.max_results = 50
+end
+```
+
+## Tools
+
+### flehmen_list_models
+
+Lists all discovered models.
+
+```
+Arguments: none
+```
+
+Returns:
+```json
+[
+  {
+    "name": "User",
+    "table_name": "users",
+    "column_count": 15,
+    "association_count": 8,
+    "enum_count": 2
+  }
+]
+```
+
+### flehmen_describe_model
+
+Returns schema details (columns, associations, enums) for a model.
+
+```
+Arguments:
+  model_name (required) - e.g. "User"
+```
+
+### flehmen_find_record
+
+Finds a single record by primary key.
+
+```
+Arguments:
+  model_name (required)
+  id         (required)
+```
+
+### flehmen_search_records
+
+Searches records with structured conditions.
+
+```
+Arguments:
+  model_name (required)
+  conditions (optional) - JSON string
+  order_by   (optional) - Column name to sort by
+  order_dir  (optional) - "asc" or "desc" (default: "asc")
+  limit      (optional)
+  offset     (optional)
+```
+
+Conditions format:
+```json
+[
+  {"field": "status", "operator": "eq", "value": "active"},
+  {"field": "created_at", "operator": "gte", "value": "2025-01-01"}
+]
+```
+
+Supported operators: `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `like`, `not_like`, `in`, `not_in`, `null`, `not_null`
+
+### flehmen_count_records
+
+Counts records matching conditions.
+
+```
+Arguments:
+  model_name (required)
+  conditions (optional) - Same format as search_records
+```
+
+### flehmen_show_associations
+
+Fetches associated records for a given record.
+
+```
+Arguments:
+  model_name       (required)
+  id               (required)
+  association_name (required) - e.g. "posts", "company"
+  limit            (optional) - For has_many associations
+  offset           (optional)
+```
+
+
+## Resources
+
+### flehmen://schema/overview
+
+Returns a JSON overview of all models including columns, associations, and enums.
+
+## Architecture
+
+```
+Flehmen.mount_in_rails(app)
+  └── FastMcp.mount_in_rails (Rack middleware)
+        ├── GET  /mcp/sse       → SSE connection (keep-alive)
+        └── POST /mcp/messages  → JSON-RPC message handling
+```
+
+- **ModelRegistry** - Auto-discovers models on first access (lazy loading)
+- **FieldFilter** - Masks sensitive fields with `[FILTERED]`
+- **QueryBuilder** - Builds Arel-based queries from structured conditions (SQL injection safe)
+- **Serializer** - Converts records to filtered hashes
+
+## Dependencies
+
+- Ruby >= 3.1.0
+- `fast-mcp` ~> 1.5
+- `activerecord` >= 7.0
+- `activesupport` >= 7.0
+- `railties` >= 7.0
+
+## License
+
+MIT

data/bin/flehmen

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+app_path = ENV["RAILS_APP_PATH"] || Dir.pwd
+ENV["RAILS_ENV"] ||= "development"
+
+require File.join(app_path, "config", "environment")
+Rails.application.eager_load!
+
+require "flehmen"
+
+Flehmen.boot!
+Flehmen.start_server!

data/lib/flehmen/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Flehmen
+  class Configuration
+    attr_accessor :models,
+                  :exclude_models,
+                  :sensitive_fields,
+                  :model_sensitive_fields,
+                  :max_results,
+                  :read_only_connection
+
+    def initialize
+      @models = :all
+      @exclude_models = []
+      @sensitive_fields = %i[
+        password_digest encrypted_password token secret
+        api_key api_secret access_token refresh_token
+        otp_secret reset_password_token confirmation_token
+        unlock_token remember_token authentication_token
+      ]
+      @model_sensitive_fields = {}
+      @max_results = 100
+      @read_only_connection = true
+    end
+  end
+end

data/lib/flehmen/field_filter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Flehmen
+  class FieldFilter
+    FILTERED_PLACEHOLDER = "[FILTERED]"
+
+    def initialize(config = Flehmen.configuration)
+      @global_sensitive = config.sensitive_fields.map(&:to_s)
+      @model_sensitive = config.model_sensitive_fields.transform_keys(&:to_s)
+                                                       .transform_values { |v| v.map(&:to_s) }
+    end
+
+    def filter_attributes(model_name, attributes_hash)
+      sensitive = sensitive_fields_for(model_name)
+      attributes_hash.each_with_object({}) do |(k, v), filtered|
+        filtered[k] = sensitive.include?(k.to_s) ? FILTERED_PLACEHOLDER : v
+      end
+    end
+
+    def visible_columns(model_name, all_columns)
+      sensitive = sensitive_fields_for(model_name)
+      all_columns.map do |col|
+        col.merge(sensitive: sensitive.include?(col[:name].to_s))
+      end
+    end
+
+    private
+
+    def sensitive_fields_for(model_name)
+      @global_sensitive + (@model_sensitive[model_name.to_s] || [])
+    end
+  end
+end

data/lib/flehmen/model_registry.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Flehmen
+  class ModelRegistry
+    attr_reader :models
+
+    def initialize(config = Flehmen.configuration)
+      @config = config
+      @models = {}
+    end
+
+    def discover!
+      base_class = defined?(ApplicationRecord) ? ApplicationRecord : ActiveRecord::Base
+      raw_models = if @config.models == :all
+                     base_class.descendants
+                   else
+                     @config.models.map { |m| m.is_a?(String) ? m.constantize : m }
+                   end
+
+      excluded = @config.exclude_models.map { |m| m.is_a?(String) ? m.constantize : m }
+
+      raw_models.each do |klass|
+        next if klass.abstract_class?
+        next if excluded.include?(klass)
+        next unless safe_table_exists?(klass)
+
+        register(klass)
+      rescue StandardError
+        # Skip models that fail introspection (e.g., STI subclasses with missing tables)
+        next
+      end
+
+      self
+    end
+
+    def model_names
+      @models.keys.sort
+    end
+
+    def find_model(name)
+      @models[name] || @models[name.to_s.classify]
+    end
+
+    private
+
+    def safe_table_exists?(klass)
+      klass.table_exists?
+    rescue StandardError
+      false
+    end
+
+    def register(klass)
+      @models[klass.name] = {
+        klass: klass,
+        table_name: klass.table_name,
+        columns: extract_columns(klass),
+        associations: extract_associations(klass),
+        enums: extract_enums(klass),
+        primary_key: klass.primary_key
+      }
+    end
+
+    def extract_columns(klass)
+      klass.columns.map do |col|
+        {
+          name: col.name,
+          type: col.type.to_s,
+          null: col.null,
+          default: col.default,
+          limit: col.limit
+        }
+      end
+    end
+
+    def extract_associations(klass)
+      klass.reflect_on_all_associations.map do |assoc|
+        {
+          name: assoc.name.to_s,
+          type: assoc.macro.to_s,
+          class_name: assoc.class_name,
+          foreign_key: assoc.foreign_key.to_s,
+          through: assoc.options[:through]&.to_s,
+          polymorphic: assoc.options[:polymorphic] || false
+        }
+      end
+    end
+
+    def extract_enums(klass)
+      return {} unless klass.respond_to?(:defined_enums)
+
+      klass.defined_enums.transform_values(&:keys)
+    end
+  end
+end

data/lib/flehmen/query_builder.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Flehmen
+  class QueryBuilder
+    ALLOWED_OPERATORS = %w[eq not_eq gt gte lt lte like not_like in not_in null not_null].freeze
+
+    def initialize(model_info, config = Flehmen.configuration)
+      @klass = model_info[:klass]
+      @column_names = model_info[:columns].map { |c| c[:name] }
+      @config = config
+    end
+
+    def build(conditions: [], order_by: nil, order_dir: "asc", limit: nil, offset: nil)
+      scope = @klass.all
+
+      conditions.each do |cond|
+        scope = apply_condition(scope, cond)
+      end
+
+      scope = apply_ordering(scope, order_by, order_dir)
+      scope = scope.limit(effective_limit(limit))
+      scope = scope.offset(offset.to_i) if offset && offset.to_i > 0
+      scope
+    end
+
+    private
+
+    def apply_condition(scope, cond)
+      field    = cond["field"]&.to_s || cond[:field]&.to_s
+      operator = cond["operator"]&.to_s || cond[:operator]&.to_s
+      value    = cond["value"] || cond[:value]
+
+      raise ArgumentError, "Missing field in condition" if field.nil? || field.empty?
+      raise ArgumentError, "Missing operator in condition" if operator.nil? || operator.empty?
+      raise ArgumentError, "Unknown column: #{field}" unless @column_names.include?(field)
+      raise ArgumentError, "Unknown operator: #{operator}" unless ALLOWED_OPERATORS.include?(operator)
+
+      table = @klass.arel_table
+
+      case operator
+      when "eq"       then scope.where(table[field].eq(value))
+      when "not_eq"   then scope.where(table[field].not_eq(value))
+      when "gt"       then scope.where(table[field].gt(value))
+      when "gte"      then scope.where(table[field].gteq(value))
+      when "lt"       then scope.where(table[field].lt(value))
+      when "lte"      then scope.where(table[field].lteq(value))
+      when "like"     then scope.where(table[field].matches(sanitize_like(value)))
+      when "not_like" then scope.where(table[field].does_not_match(sanitize_like(value)))
+      when "in"       then scope.where(table[field].in(Array(value).first(@config.max_results)))
+      when "not_in"   then scope.where(table[field].not_in(Array(value).first(@config.max_results)))
+      when "null"     then scope.where(table[field].eq(nil))
+      when "not_null" then scope.where(table[field].not_eq(nil))
+      end
+    end
+
+    def apply_ordering(scope, order_by, order_dir)
+      return scope.order(id: :asc) unless order_by
+
+      raise ArgumentError, "Unknown column: #{order_by}" unless @column_names.include?(order_by.to_s)
+
+      dir = %w[asc desc].include?(order_dir.to_s.downcase) ? order_dir.to_s.downcase.to_sym : :asc
+      scope.order(order_by.to_sym => dir)
+    end
+
+    def effective_limit(requested)
+      max = @config.max_results
+      return max unless requested
+
+      [requested.to_i, max].min
+    end
+
+    def sanitize_like(value)
+      # Escape special LIKE characters to prevent unintended wildcards
+      value.to_s.gsub("\\", "\\\\\\\\").gsub("%", "\\%").gsub("_", "\\_")
+    end
+  end
+end

data/lib/flehmen/resources/schema_overview_resource.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flehmen
+  module Resources
+    class SchemaOverviewResource < FastMcp::Resource
+      uri "flehmen://schema/overview"
+      resource_name "Database Schema Overview"
+      description "Complete overview of all available models, their columns, associations, and enums"
+      mime_type "application/json"
+
+      def content
+        registry = Flehmen.model_registry
+        filter = Flehmen::FieldFilter.new
+
+        overview = registry.model_names.map do |name|
+          info = registry.find_model(name)
+          {
+            model: name,
+            table: info[:table_name],
+            primary_key: info[:primary_key],
+            columns: filter.visible_columns(name, info[:columns]),
+            associations: info[:associations],
+            enums: info[:enums]
+          }
+        end
+
+        JSON.pretty_generate(overview)
+      end
+    end
+  end
+end

data/lib/flehmen/serializer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Flehmen
+  class Serializer
+    def initialize(field_filter = FieldFilter.new)
+      @field_filter = field_filter
+    end
+
+    def serialize_record(record)
+      model_name = record.class.name
+      @field_filter.filter_attributes(model_name, record.attributes)
+    end
+
+    def serialize_records(records)
+      records.map { |r| serialize_record(r) }
+    end
+  end
+end

data/lib/flehmen/tools/base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Flehmen
+  module Tools
+    class Base < FastMcp::Tool
+      def call(**args)
+        ActiveRecord::Base.while_preventing_writes(Flehmen.configuration.read_only_connection) do
+          execute(**args)
+        end
+      end
+    end
+  end
+end

data/lib/flehmen/tools/count_records_tool.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flehmen
+  module Tools
+    class CountRecordsTool < Base
+      tool_name "flehmen_count_records"
+      description 'Count records matching filter conditions. Example conditions: [{"field":"status","operator":"eq","value":"active"}]'
+
+      arguments do
+        required(:model_name).filled(:string).description("Name of the model class")
+        optional(:conditions).filled(:string).description('JSON array of conditions: [{"field":"...", "operator":"...", "value":"..."}]')
+      end
+
+      annotations(
+        read_only_hint: true,
+        open_world_hint: false
+      )
+
+      def execute(model_name:, conditions: nil)
+        info = Flehmen.model_registry.find_model(model_name)
+        return JSON.generate({ error: "Model not found: #{model_name}" }) unless info
+
+        parsed_conditions = conditions ? JSON.parse(conditions) : []
+
+        builder = Flehmen::QueryBuilder.new(info)
+        scope = builder.build(conditions: parsed_conditions, limit: nil)
+        count = scope.unscope(:limit, :offset, :order).count
+
+        JSON.generate({ model: model_name, count: count })
+      rescue JSON::ParserError
+        JSON.generate({ error: "Invalid JSON in conditions parameter" })
+      rescue ArgumentError => e
+        JSON.generate({ error: e.message })
+      end
+    end
+  end
+end

data/lib/flehmen/tools/describe_model_tool.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flehmen
+  module Tools
+    class DescribeModelTool < Base
+      tool_name "flehmen_describe_model"
+      description "Show the full schema for a model: columns (name, type, null, default), associations (name, type, target class), and enum definitions"
+
+      arguments do
+        required(:model_name).filled(:string).description("Name of the model class, e.g. 'User' or 'Post'")
+      end
+
+      annotations(
+        read_only_hint: true,
+        open_world_hint: false
+      )
+
+      def execute(model_name:)
+        info = Flehmen.model_registry.find_model(model_name)
+        return JSON.generate({ error: "Model not found: #{model_name}" }) unless info
+
+        filter = Flehmen::FieldFilter.new
+        result = {
+          model: model_name,
+          table_name: info[:table_name],
+          primary_key: info[:primary_key],
+          columns: filter.visible_columns(model_name, info[:columns]),
+          associations: info[:associations],
+          enums: info[:enums]
+        }
+        JSON.generate(result)
+      end
+    end
+  end
+end

data/lib/flehmen/tools/find_record_tool.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flehmen
+  module Tools
+    class FindRecordTool < Base
+      tool_name "flehmen_find_record"
+      description "Find a single record by its primary key (usually ID)"
+
+      arguments do
+        required(:model_name).filled(:string).description("Name of the model class")
+        required(:id).filled(:string).description("Primary key value of the record")
+      end
+
+      annotations(
+        read_only_hint: true,
+        open_world_hint: false
+      )
+
+      def execute(model_name:, id:)
+        info = Flehmen.model_registry.find_model(model_name)
+        return JSON.generate({ error: "Model not found: #{model_name}" }) unless info
+
+        record = info[:klass].find_by(info[:primary_key] => id)
+        return JSON.generate({ error: "Record not found: #{model_name}##{id}" }) unless record
+
+        serializer = Flehmen::Serializer.new
+        JSON.generate(serializer.serialize_record(record))
+      end
+    end
+  end
+end

data/lib/flehmen/tools/list_models_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flehmen
+  module Tools
+    class ListModelsTool < Base
+      tool_name "flehmen_list_models"
+      description "List all available ActiveRecord models with their table names, column counts, and association counts"
+
+      annotations(
+        read_only_hint: true,
+        open_world_hint: false
+      )
+
+      def execute(**_args)
+        registry = Flehmen.model_registry
+        models = registry.model_names.map do |name|
+          info = registry.find_model(name)
+          {
+            name: name,
+            table_name: info[:table_name],
+            column_count: info[:columns].size,
+            association_count: info[:associations].size,
+            enum_count: info[:enums].size
+          }
+        end
+        JSON.generate(models)
+      end
+    end
+  end
+end

data/lib/flehmen/tools/search_records_tool.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flehmen
+  module Tools
+    class SearchRecordsTool < Base
+      tool_name "flehmen_search_records"
+      description 'Search records with filter conditions. Each condition has a field, operator (eq, not_eq, gt, gte, lt, lte, like, in, null, not_null), and value. Example conditions: [{"field":"status","operator":"eq","value":"active"}]'
+
+      arguments do
+        required(:model_name).filled(:string).description("Name of the model class")
+        optional(:conditions).filled(:string).description('JSON array of conditions: [{"field":"...", "operator":"...", "value":"..."}]')
+        optional(:order_by).filled(:string).description("Column name to order by")
+        optional(:order_dir).filled(:string).description("Order direction: 'asc' or 'desc'")
+        optional(:limit).filled(:integer).value(gteq?: 1, lteq?: 100).description("Max records to return (capped by server config)")
+        optional(:offset).filled(:integer).value(gteq?: 0, lteq?: 10000).description("Number of records to skip for pagination")
+      end
+
+      annotations(
+        read_only_hint: true,
+        open_world_hint: false
+      )
+
+      def execute(model_name:, conditions: nil, order_by: nil, order_dir: "asc", limit: nil, offset: nil)
+        info = Flehmen.model_registry.find_model(model_name)
+        return JSON.generate({ error: "Model not found: #{model_name}" }) unless info
+
+        parsed_conditions = conditions ? JSON.parse(conditions) : []
+
+        builder = Flehmen::QueryBuilder.new(info)
+        records = builder.build(
+          conditions: parsed_conditions,
+          order_by: order_by,
+          order_dir: order_dir,
+          limit: limit,
+          offset: offset
+        )
+
+        serializer = Flehmen::Serializer.new
+        result = {
+          model: model_name,
+          count: records.size,
+          records: serializer.serialize_records(records)
+        }
+        JSON.generate(result)
+      rescue JSON::ParserError
+        JSON.generate({ error: "Invalid JSON in conditions parameter" })
+      rescue ArgumentError => e
+        JSON.generate({ error: e.message })
+      end
+    end
+  end
+end

data/lib/flehmen/tools/show_associations_tool.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flehmen
+  module Tools
+    class ShowAssociationsTool < Base
+      tool_name "flehmen_show_associations"
+      description "Navigate a record's associations. Given a model, record ID, and association name, returns the associated records."
+
+      arguments do
+        required(:model_name).filled(:string).description("Name of the source model class")
+        required(:id).filled(:string).description("Primary key of the source record")
+        required(:association_name).filled(:string).description("Name of the association to navigate")
+        optional(:limit).filled(:integer).value(gteq?: 1, lteq?: 100).description("Max associated records to return")
+        optional(:offset).filled(:integer).value(gteq?: 0, lteq?: 10000).description("Number of records to skip")
+      end
+
+      annotations(
+        read_only_hint: true,
+        open_world_hint: false
+      )
+
+      def execute(model_name:, id:, association_name:, limit: nil, offset: nil)
+        info = Flehmen.model_registry.find_model(model_name)
+        return JSON.generate({ error: "Model not found: #{model_name}" }) unless info
+
+        # Validate association name against declared associations
+        valid_associations = info[:associations].map { |a| a[:name] }
+        unless valid_associations.include?(association_name)
+          return JSON.generate({ error: "Unknown association: #{association_name}" })
+        end
+
+        record = info[:klass].find_by(info[:primary_key] => id)
+        return JSON.generate({ error: "Record not found: #{model_name}##{id}" }) unless record
+
+        assoc_meta = info[:associations].find { |a| a[:name] == association_name }
+        associated = record.public_send(association_name)
+
+        serializer = Flehmen::Serializer.new
+        max = Flehmen.configuration.max_results
+
+        if %w[has_many has_and_belongs_to_many].include?(assoc_meta[:type])
+          effective_limit = limit ? [limit.to_i, max].min : max
+          scope = associated.limit(effective_limit)
+          scope = scope.offset(offset.to_i) if offset && offset.to_i > 0
+          records = scope.to_a
+
+          JSON.generate({
+            source: "#{model_name}##{id}",
+            association: association_name,
+            type: assoc_meta[:type],
+            count: records.size,
+            records: serializer.serialize_records(records)
+          })
+        else
+          # belongs_to / has_one
+          if associated
+            JSON.generate({
+              source: "#{model_name}##{id}",
+              association: association_name,
+              type: assoc_meta[:type],
+              record: serializer.serialize_record(associated)
+            })
+          else
+            JSON.generate({
+              source: "#{model_name}##{id}",
+              association: association_name,
+              type: assoc_meta[:type],
+              record: nil
+            })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flehmen/version.rb

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

data/lib/flehmen.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+require_relative "flehmen/version"
+require_relative "flehmen/configuration"
+require_relative "flehmen/model_registry"
+require_relative "flehmen/field_filter"
+require_relative "flehmen/query_builder"
+require_relative "flehmen/serializer"
+require_relative "flehmen/tools/base"
+require_relative "flehmen/tools/list_models_tool"
+require_relative "flehmen/tools/describe_model_tool"
+require_relative "flehmen/tools/find_record_tool"
+require_relative "flehmen/tools/search_records_tool"
+require_relative "flehmen/tools/count_records_tool"
+require_relative "flehmen/tools/show_associations_tool"
+require_relative "flehmen/resources/schema_overview_resource"
+
+module Flehmen
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      @model_registry = nil
+    end
+
+    # Lazily discover models on first access
+    def model_registry
+      @model_registry || boot!
+    end
+
+    def boot!
+      @model_registry = ModelRegistry.new(configuration)
+      @model_registry.discover!
+    end
+
+    def start_server!
+      server = build_server
+      server.start
+    end
+
+    def mount_in_rails(app, options = {})
+      opts = {
+        name: "flehmen",
+        version: Flehmen::VERSION,
+        path_prefix: options.delete(:path_prefix) || "/mcp"
+      }.merge(options)
+
+      FastMcp.mount_in_rails(app, opts) do |server|
+        register_tools(server)
+        register_resources(server)
+      end
+    end
+
+    private
+
+    def build_server
+      server = FastMcp::Server.new(
+        name: "flehmen",
+        version: Flehmen::VERSION
+      )
+      register_tools(server)
+      register_resources(server)
+      server
+    end
+
+    def register_tools(server)
+      server.register_tool(Tools::ListModelsTool)
+      server.register_tool(Tools::DescribeModelTool)
+      server.register_tool(Tools::FindRecordTool)
+      server.register_tool(Tools::SearchRecordsTool)
+      server.register_tool(Tools::CountRecordsTool)
+      server.register_tool(Tools::ShowAssociationsTool)
+    end
+
+    def register_resources(server)
+      server.register_resource(Resources::SchemaOverviewResource)
+    end
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: flehmen
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ryosk7
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fast-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: A generic Ruby gem that auto-discovers ActiveRecord models and provides
+  read-only query tools via the Model Context Protocol (MCP) for Claude Desktop integration.
+executables:
+- flehmen
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/flehmen
+- lib/flehmen.rb
+- lib/flehmen/configuration.rb
+- lib/flehmen/field_filter.rb
+- lib/flehmen/model_registry.rb
+- lib/flehmen/query_builder.rb
+- lib/flehmen/resources/schema_overview_resource.rb
+- lib/flehmen/serializer.rb
+- lib/flehmen/tools/base.rb
+- lib/flehmen/tools/count_records_tool.rb
+- lib/flehmen/tools/describe_model_tool.rb
+- lib/flehmen/tools/find_record_tool.rb
+- lib/flehmen/tools/list_models_tool.rb
+- lib/flehmen/tools/search_records_tool.rb
+- lib/flehmen/tools/show_associations_tool.rb
+- lib/flehmen/version.rb
+homepage: https://github.com/ryosk7/flehmen
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: MCP server gem that exposes Rails ActiveRecord models to Claude Desktop
+test_files: []