ask-rails-harness-mcp 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 10bdd0fdd7f2b5ad18f3953a8d87474c5df24a4c21ae3e5bfbd9945c2e21bb67
+  data.tar.gz: 50fb399f513255f82626819688d5afc898b6fcab709adf7126a5a93b57c7176a
+SHA512:
+  metadata.gz: '0383729111ae526ea38c8a7a12e13310bb4c705c876f55b2a4b0ba2afacc65ff330be644bd5e134dc4fc77568200092f48546e2f8ed81663c697742782634f96'
+  data.tar.gz: 5c1791fdc69510e5fd48acf49b764a73129b5bbe37e0cf47877ef147386191bf5df3b7bdcf612760e6c0f7f63e3d782fab859b81358a99446ebe8d274250fc7c

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+## [0.2.0] — 2026-07-23
+
+### Added
+
+- **stdio transport** — `Ask::Rails::MCP.start` boots the Rails app and starts a stdio MCP server. Run `ask-rails-mcp` from your Rails app root.
+- **`bin/ask-rails-mcp`** — CLI entry point for local development. No web server needed.
+
+## [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,107 @@
+# ask-rails-harness-mcp
+
+MCP server for Rails app introspection. Exposes all [ask-rails-harness](https://github.com/ask-rb/ask-rails-harness) 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-harness uses internally.
+
+## Installation
+
+```bash
+bundle add ask-rails-harness-mcp
+```
+
+## Usage
+
+### Option 1: stdio (local development — recommended)
+
+Run from your Rails app root:
+
+```bash
+cd my-rails-app
+ask-rails-harness-mcp
+```
+
+This boots your Rails app and starts an MCP stdio server. Configure in your agent's MCP config:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "ask-rails-harness-mcp": {
+        "type": "stdio",
+        "command": "ask-rails-harness-mcp",
+        "args": []
+      }
+    }
+  }
+}
+```
+
+### Option 2: HTTP endpoint (remote/production)
+
+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:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "ask-rails-harness-mcp": {
+        "type": "http",
+        "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::Harness::Auth` system as the chat UI:
+
+```ruby
+Ask::Rails::Harness::Auth.check = -> {
+  redirect_to main_app.login_path unless current_user&.admin?
+}
+```
+
+### Safety
+
+All ask-rails-harness 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/bin/ask-rails-harness-mcp

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ask-rails-harness-mcp"
+
+Ask::Rails::MCP.start

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

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

data/lib/ask/rails/mcp.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "ask/rails/harness"
+require "ask/mcp"
+require_relative "mcp/version"
+
+module Ask
+  module Rails
+    module MCP
+      PROTOCOL_VERSION = "2025-06-18"
+
+      class << self
+        # All ask-rails-harness tools wrapped as MCP tool instances.
+        def tools
+          @tools ||= Ask::Rails::Harness::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-harness-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
+
+        # Start the MCP stdio server, auto-loading the Rails app.
+        #
+        #   $ ask-rails-harness-mcp
+        #
+        # The server will listen for JSON-RPC messages on stdin and write
+        # responses to stdout — the standard MCP stdio transport. Register
+        # this executable as an MCP server in your client configuration:
+        #
+        #   "mcp": {
+        #     "servers": {
+        #       "ask-rails-harness-mcp": {
+        #         "type": "stdio",
+        #         "command": "ask-rails-harness-mcp",
+        #         "args": []
+        #       }
+        #     }
+        #   }
+        def start
+          load_rails_app
+
+          Ask::MCP::Server.start_stdio(
+            name: "ask-rails-harness-mcp",
+            tools: tools,
+            capabilities: { tools: {} },
+            debug: ENV["DEBUG"] == "1"
+          )
+        end
+
+        # Get or clear the cache (useful in tests).
+        def reset!
+          @tools = nil
+          @tool_server = nil
+          @initialized = false
+        end
+
+        private
+
+        def load_rails_app
+          return if defined?(::Rails) && ::Rails.application
+          require File.expand_path("config/environment")
+        rescue LoadError
+          warn "ask-rails-harness-mcp: must be run from your Rails app root (config/environment.rb not found)"
+          exit 1
+        end
+
+        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-harness-mcp.rb

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

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: ask-rails-harness-mcp
+version: !ruby/object:Gem::Version
+  version: 0.2.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-harness
+  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: 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-harness 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:
+- ask-rails-harness-mcp
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- bin/ask-rails-harness-mcp
+- lib/ask-rails-harness-mcp.rb
+- lib/ask/rails/mcp.rb
+- lib/ask/rails/mcp/version.rb
+homepage: https://github.com/ask-rb/ask-rails-harness-mcp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-rails-harness-mcp
+  source_code_uri: https://github.com/ask-rb/ask-rails-harness-mcp
+  changelog_uri: https://github.com/ask-rb/ask-rails-harness-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-harness tools
+  over the Model Context Protocol
+test_files: []