ask-rails-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0735b5cd8de91ba218011330ce945aaf843cb2b84d1a98e382b54cbe3f7ef51f
+  data.tar.gz: 6cec7455ddc917a6b3482fe5cb9e72c2ffefd168f3f1310b93fbf6570ad0ece3
+SHA512:
+  metadata.gz: 972281e304211d8939710ef5c6167313fcd0945b7d30204642d5be58f6c8f7c4f41fc3ea1159d4c04cb013059ad7b803fe455d086175e5383327e90709a1f970
+  data.tar.gz: 61f31bccee0eb59227266ea2e23637fe4b5f616db9d4a6d40d6b2df56c3251a951e8c31294503ba5b3209e8c59635a78c897852b125c93046371ef1a831ab24e

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+## [0.1.0] — 2026-07-23
+
+### Added
+
+- **MCP endpoint** — Mount an MCP server in your Rails app that exposes all ask-rails tools (SchemaGraph, QueryDatabase, ReadModel, RouteInspector, ReadLog, SearchCodebase, ReadFile, RunCommand, ReadRoutes) over the Model Context Protocol.
+- **JSON-RPC handler** — `Ask::Rails::MCP.handle` processes MCP messages (`initialize`, `tools/list`, `tools/call`, `ping`) and returns proper JSON-RPC responses.
+- **Tool definitions** — All 9 tools are automatically registered with their names, descriptions, and JSON Schema input definitions.
+- **Auth** — The MCP endpoint respects `Ask::Rails::Auth.check` for authentication.
+
+### Usage
+
+Mount in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  # Protect behind your auth
+  authenticate :user, ->(u) { u.admin? } do
+    post "ask/mcp", to: "ask/rails/mcp#handle"
+  end
+end
+```

data/README.md

@@ -0,0 +1,80 @@
+# ask-rails-mcp
+
+MCP server for Rails app introspection. Exposes all [ask-rails](https://github.com/ask-rb/ask-rails) tools over the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+Coding agents like Claude Code, Cursor, or any MCP-compatible client can connect to inspect your Rails schema, query your database, read models, and more — all through the same tools ask-rails uses internally.
+
+## Installation
+
+```bash
+bundle add ask-rails-mcp
+```
+
+## Usage
+
+Mount in `config/routes.rb` behind your existing auth:
+
+```ruby
+Rails.application.routes.draw do
+  authenticate :user, ->(u) { u.admin? } do
+    post "ask/mcp", to: "ask/rails/mcp#handle"
+  end
+end
+```
+
+Then configure any MCP-compatible agent to connect to your app. For example, in Claude Code's `~/.claude/settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "ask-rails-mcp": {
+        "type": "url",
+        "url": "https://myapp.com/ask/mcp"
+      }
+    }
+  }
+}
+```
+
+The agent discovers 9 tools automatically:
+
+| Tool | What it does |
+|---|---|
+| `schema_graph` | Full schema introspection — all models, tables, columns, associations, validations |
+| `query_database` | Read-only SQL queries with safety guards |
+| `read_model` | Introspect a single ActiveRecord model |
+| `route_inspector` | Parsed route table with filters |
+| `read_log` | Read Rails log files with level/search filtering |
+| `search_codebase` | Full-text grep search |
+| `read_file` | Read any file from `Rails.root` |
+| `run_command` | Run shell commands in the app root |
+| `read_routes` | Read the raw `config/routes.rb` |
+
+### Authentication
+
+The MCP endpoint uses the same `Ask::Rails::Auth` system as the chat UI:
+
+```ruby
+Ask::Rails::Auth.check = -> {
+  redirect_to main_app.login_path unless current_user&.admin?
+}
+```
+
+### Safety
+
+All ask-rails safety features apply automatically:
+- **Permissions** — access modes (`:read_only`, `:ask_before_changes`, `:full_access`)
+- **Command allowlists** — `allowed_commands` / `denied_commands` for `RunCommand`
+- **Write guards** — `INSERT`/`UPDATE`/`DELETE` blocked by `QueryDatabase`
+- **Audit log** — every tool call recorded in `ask_audit_logs`
+
+## Development
+
+```bash
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/rails/mcp/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module MCP
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/ask/rails/mcp.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "ask/rails"
+require "ask/mcp"
+require_relative "mcp/version"
+
+module Ask
+  module Rails
+    module MCP
+      PROTOCOL_VERSION = "2025-06-18"
+
+      class << self
+        # All ask-rails tools wrapped as MCP tool instances.
+        def tools
+          @tools ||= Ask::Rails::CORE_RAILS_TOOLS.map(&:new)
+        end
+
+        # Tool server adapter that dispatches tools/call requests.
+        def tool_server
+          @tool_server ||= Ask::MCP::Adapters::ToolServer.new(tools)
+        end
+
+        # Handle a raw JSON-RPC message string.
+        # Returns a Hash suitable for JSON serialization.
+        def handle(json_string)
+          msg = JSON.parse(json_string)
+          process_message(msg)
+        rescue JSON::ParserError => e
+          error_response(nil, -32700, "Parse error: #{e.message}")
+        end
+
+        # Handle a parsed JSON-RPC message hash.
+        def process_message(msg)
+          method_name = msg["method"]
+          id = msg["id"]
+          params = msg["params"] || {}
+          has_id = msg.key?("id")
+
+          case method_name
+          when "initialize"
+            handle_initialize(id, params)
+          when "notifications/initialized"
+            @initialized = true
+            nil  # Notification — no response
+          when "tools/list"
+            @initialized ? handle_tools_list(id) : error_response(id, -32000, "Server not initialized")
+          when "tools/call"
+            @initialized ? handle_tool_call(id, params) : error_response(id, -32000, "Server not initialized")
+          when "ping"
+            has_id ? success_response(id, {}) : nil
+          else
+            has_id ? error_response(id, -32601, "Method not found: #{method_name}") : nil
+          end
+        end
+
+        # Process an initialize request.
+        def handle_initialize(id, params)
+          @initialized = true
+          client_version = params["protocolVersion"] || PROTOCOL_VERSION
+          success_response(id, {
+            "protocolVersion" => client_version,
+            "capabilities" => { "tools" => {} },
+            "serverInfo" => {
+              "name" => "ask-rails-mcp",
+              "version" => Ask::Rails::MCP::VERSION
+            }
+          })
+        end
+
+        # Process a tools/list request.
+        def handle_tools_list(id)
+          defs = tool_server.definitions
+          success_response(id, { tools: defs })
+        end
+
+        # Process a tools/call request.
+        def handle_tool_call(id, params)
+          tool_name = params["name"]
+          arguments = params["arguments"] || {}
+
+          result = tool_server.call(tool_name, arguments)
+          success_response(id, result)
+        end
+
+        # Get or clear the cache (useful in tests).
+        def reset!
+          @tools = nil
+          @tool_server = nil
+          @initialized = false
+        end
+
+        private
+
+        def success_response(id, result)
+          { "jsonrpc" => "2.0", "id" => id, "result" => deep_stringify_keys(result) }
+        end
+
+        def error_response(id, code, message)
+          { "jsonrpc" => "2.0", "id" => id, "error" => { "code" => code, "message" => message } }
+        end
+
+        def deep_stringify_keys(obj)
+          case obj
+          when Hash then obj.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify_keys(v) }
+          when Array then obj.map { |v| deep_stringify_keys(v) }
+          else obj
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask-rails-mcp.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ask/rails/mcp"

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: ask-rails-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: ask-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  Mount an MCP endpoint in your Rails app that exposes SchemaGraph, QueryDatabase,
+  ReadModel, RouteInspector, and all other ask-rails tools as MCP tools.
+  Coding agents like Claude Code, Cursor, or any MCP-compatible client can
+  connect to inspect your schema, query your database, read models, and more.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/ask-rails-mcp.rb
+- lib/ask/rails/mcp.rb
+- lib/ask/rails/mcp/version.rb
+homepage: https://github.com/ask-rb/ask-rails-mcp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-rails-mcp
+  source_code_uri: https://github.com/ask-rb/ask-rails-mcp
+  changelog_uri: https://github.com/ask-rb/ask-rails-mcp/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: MCP server for Rails app introspection — exposes ask-rails tools over the
+  Model Context Protocol
+test_files: []