hitch-rails 0.2.0

data/lib/generators/hitch/install/templates/controller.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+<% @controller_modules.each_with_index do |namespace, index| -%>
+<%= "  " * index %>module <%= namespace %>
+<% end -%>
+<%= "  " * @controller_modules.length %>class <%= @controller_leaf %> < ActionController::API
+<%= "  " * (@controller_modules.length + 1) %>include Hitch::MCP::Endpoint
+<%= "  " * @controller_modules.length %>end
+<% @controller_modules.length.times.reverse_each do |index| -%>
+<%= "  " * index %>end
+<% end -%>

data/lib/generators/hitch/install/templates/initializer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# hitch-rails configuration. These are the knobs every host must set; the
+# full reference (proxy hosts, scopes, token lifetimes, byte caps, rate
+# limits) lives at github.com/tylerklose/hitch-rails.
+Hitch.configure do |config|
+  # This MCP server's canonical resource URI for RFC 8707 audience binding.
+  # MUST match what MCP clients send in the `resource` parameter.
+  config.resource_uri = "https://your-app.example.com/mcp"
+
+  # Display name shown on the OAuth consent screen.
+  config.brand_name = "Your App"
+
+  # Where to send a signed-out visitor who lands on the consent screen.
+  # Without it the browser OAuth flow answers a bare 401 and no MCP client
+  # can complete sign-in. "/session/new" is what Rails 8's own
+  # `bin/rails generate authentication` creates; Devise uses
+  # "/users/sign_in".
+  config.login_path = "/session/new"
+
+  # Exact browser origins allowed to call the endpoint, including scheme and
+  # non-default port. Denied by default; development and test also accept
+  # loopback origins.
+  config.allowed_origins = []
+
+  # Client ID Metadata Documents — how MCP 2026-07-28 clients register.
+  # Requires DIRECT outbound https on port 443 (Hitch deliberately ignores
+  # http_proxy); set false if this tier has no direct egress. Verify with:
+  #   bin/rails 'hitch:cimd:check[https://some-client.example/client.json]'
+  config.client_id_metadata_enabled = true
+
+  # Dynamic Client Registration is unauthenticated and deprecated by the MCP
+  # specification, so new installations do not expose it.
+  config.dynamic_client_registration_enabled = false
+
+  # The authenticated /mcp endpoint. Tools stay deny-default until they are
+  # reviewed and registered in app/tools/mcp_tool_registry.rb.
+  config.mcp.enabled = true
+  config.mcp.registry = "McpToolRegistry"
+end

data/lib/generators/hitch/install/templates/registry.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Tools are listed and callable only when registered here. Generate one with
+# `bin/rails generate hitch:tool NAME`.
+class McpToolRegistry < Hitch::MCP::Registry
+end

data/lib/generators/hitch/tool/templates/tool.rb.tt

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+<% @class_modules.each_with_index do |namespace, index| -%>
+<%= "  " * index %>module <%= namespace %>
+<% end -%>
+<%= "  " * @class_modules.length %>class <%= @class_leaf %> < Hitch::MCP::Tool
+<%= "  " * (@class_modules.length + 1) %>tool_name "<%= @tool_name %>"
+<%= "  " * (@class_modules.length + 1) %>description "TODO: describe <%= @tool_name %>"
+<%= "  " * (@class_modules.length + 1) %>input_schema(
+<%= "  " * (@class_modules.length + 2) %>type: "object",
+<%= "  " * (@class_modules.length + 2) %>properties: {},
+<%= "  " * (@class_modules.length + 2) %>additionalProperties: false
+<%= "  " * (@class_modules.length + 1) %>)
+<% if deny_default? -%>
+<%= "  " * (@class_modules.length + 1) %>annotations read_only_hint: false,
+<%= "  " * (@class_modules.length + 2) %>destructive_hint: true,
+<%= "  " * (@class_modules.length + 2) %>idempotent_hint: false,
+<%= "  " * (@class_modules.length + 2) %>open_world_hint: true
+
+<%= "  " * (@class_modules.length + 1) %>def self.available_to?(_context)
+<%= "  " * (@class_modules.length + 2) %>false
+<%= "  " * (@class_modules.length + 1) %>end
+
+<%= "  " * (@class_modules.length + 1) %>def self.authorize!(_context, arguments:)
+<%= "  " * (@class_modules.length + 2) %>raise Hitch::MCP::Forbidden
+<%= "  " * (@class_modules.length + 1) %>end
+
+<%= "  " * (@class_modules.length + 1) %>def self.perform(_context, arguments:)
+<%= "  " * (@class_modules.length + 2) %>raise "Implement <%= @class_name %>.perform before making the tool available"
+<%= "  " * (@class_modules.length + 1) %>end
+<% else -%>
+<%= "  " * (@class_modules.length + 1) %>annotations read_only_hint: true,
+<%= "  " * (@class_modules.length + 2) %>destructive_hint: false,
+<%= "  " * (@class_modules.length + 2) %>idempotent_hint: true,
+<%= "  " * (@class_modules.length + 2) %>open_world_hint: false
+
+<%= "  " * (@class_modules.length + 1) %>def self.available_to?(_context)
+<%= "  " * (@class_modules.length + 2) %>true
+<%= "  " * (@class_modules.length + 1) %>end
+
+<%= "  " * (@class_modules.length + 1) %>def self.authorize!(_context, arguments:)
+<%= "  " * (@class_modules.length + 2) %># Returning without raising ALLOWS the call. Put your policy here,
+<%= "  " * (@class_modules.length + 2) %># naming the context argument to use it:
+<%= "  " * (@class_modules.length + 2) %>#   raise Hitch::MCP::Forbidden unless context.principal.admin?
+<%= "  " * (@class_modules.length + 1) %>end
+
+<%= "  " * (@class_modules.length + 1) %>def self.perform(_context, arguments:)
+<%= "  " * (@class_modules.length + 2) %>Hitch::MCP::Result.text("<%= @tool_name %> is wired up; implement perform to do real work")
+<%= "  " * (@class_modules.length + 1) %>end
+<% end -%>
+<%= "  " * @class_modules.length %>end
+<% @class_modules.length.times.reverse_each do |index| -%>
+<%= "  " * index %>end
+<% end -%>

data/lib/generators/hitch/tool/templates/tool_test.rb.tt

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "hitch/mcp/test_helper"
+
+class <%= @test_class_name %> < ActionDispatch::IntegrationTest
+  # post_mcp drives your mounted /mcp endpoint over real HTTP — see
+  # Hitch::MCP::TestHelper.
+  include Hitch::MCP::TestHelper
+
+  setup do
+    # post_mcp needs a real bearer token. Point this at however your tests
+    # get a signed-in user — a fixture, a factory, or a record created here.
+    @token = mint_mcp_token(principal: User.first!)
+  end
+<% if deny_default? -%>
+
+  test "stays hidden until the host implements and opens it" do
+    post_mcp(method: "tools/list", token: @token)
+
+    assert_response :success
+    tools = JSON.parse(response.body).dig("result", "tools")
+    refute_includes tools.map { |tool| tool.fetch("name") }, "<%= @tool_name %>"
+  end
+
+  test "calls are refused while unavailable" do
+    post_mcp(
+      method: "tools/call",
+      token: @token,
+      params: { name: "<%= @tool_name %>", arguments: {} }
+    )
+
+    assert_response :success
+    assert_equal(-32602, JSON.parse(response.body).dig("error", "code"))
+  end
+<% else -%>
+
+  test "is listed for an authorized principal" do
+    post_mcp(method: "tools/list", token: @token)
+
+    assert_response :success
+    tools = JSON.parse(response.body).dig("result", "tools")
+    assert_includes tools.map { |tool| tool.fetch("name") }, "<%= @tool_name %>"
+  end
+
+  test "responds when called" do
+    post_mcp(
+      method: "tools/call",
+      token: @token,
+      params: { name: "<%= @tool_name %>", arguments: {} }
+    )
+
+    assert_response :success
+    result = JSON.parse(response.body).fetch("result")
+    assert_includes result.dig("content", 0, "text"), "<%= @tool_name %>"
+  end
+<% end -%>
+end

data/lib/generators/hitch/tool_generator.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "rails/generators"
+require_relative "generator_guards"
+
+module Hitch
+  module Generators
+    # Generates a working, registered MCP tool plus an integration test that
+    # proves it responds over real HTTP. --deny-default emits a hardened
+    # variant instead: unavailable, denying, and unimplemented until the
+    # host fills it in.
+    #
+    # Usage:
+    #   bin/rails generate hitch:tool NAME
+    #   bin/rails destroy hitch:tool NAME
+    class ToolGenerator < ::Rails::Generators::Base
+      include Hitch::Generators::GeneratorGuards
+
+      namespace "hitch:tool"
+
+      source_root File.expand_path("tool/templates", __dir__)
+
+      argument :name, type: :string, required: true,
+        desc: "Tool name, optionally nested with / or ::"
+      class_option :namespace,
+        type: :string,
+        default: "McpTools",
+        desc: "Root Ruby namespace for the generated tool"
+      class_option :deny_default,
+        type: :boolean,
+        default: false,
+        desc: "Generate the hardened variant: unavailable and denying until implemented"
+
+      NAME_SEGMENT_PATTERN =
+        /\A(?:[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*|[A-Z][A-Za-z0-9]*)\z/
+      CANONICAL_SEGMENT_PATTERN = /\A[a-z][a-z0-9]*(?:_[a-z0-9]+)*\z/
+      NAMESPACE_PATTERN = /\A[A-Z][A-Za-z0-9]*(?:::[A-Z][A-Za-z0-9]*)*\z/
+
+      def self.exit_on_failure?
+        true
+      end
+
+      def generate_or_revoke
+        prepare_identity!
+        behavior == :revoke ? preflight_revoke! : preflight!
+
+        # Behavior-aware Thor actions: create/inject in invoke, remove in
+        # revoke.
+        template "tool.rb.tt", @tool_path
+        template "tool_test.rb.tt", @test_path
+        inject_into_class REGISTRY_PATH, "McpToolRegistry", "  #{@registration_line}\n"
+
+        print_next_steps unless behavior == :revoke
+      end
+
+      private
+
+      # inject_into_class revokes by exact bytes; a reformatted registration
+      # line would survive while the tool file disappears, stranding a
+      # NameError at the next boot. Refuse the whole rollback instead.
+      def preflight_revoke!
+        registry = destination_file?(REGISTRY_PATH) ? File.binread(destination_path(REGISTRY_PATH)) : ""
+        return unless registry.match?(/^\s*register\s+#{Regexp.escape(@class_name)}\b/)
+        return if registry.include?(@registration_line)
+
+        refuse!("rollback", [
+          "#{REGISTRY_PATH} contains an edited registration for #{@class_name}; " \
+          "remove that line by hand, then rerun bin/rails destroy hitch:tool"
+        ])
+      end
+
+      def preflight!
+        errors = []
+        [ @tool_path, @test_path ].each do |path|
+          errors << "file collision: #{path}" if destination_file?(path)
+        end
+        errors << "constant collision: #{@class_name}" if constant_collision?(@class_name)
+        errors << "constant collision: #{@test_class_name}" if constant_collision?(@test_class_name)
+        errors << "#{REGISTRY_PATH} is missing; run `bin/rails generate hitch:install` first" unless
+          destination_file?(REGISTRY_PATH)
+        refuse!("generation", errors) if errors.any?
+      end
+
+      def prepare_identity!
+        namespace = options.fetch("namespace")
+        canonical_segments = normalize_name(name)
+        errors = []
+        errors << "name must contain valid snake-case, kebab-case, or constant segments" unless canonical_segments
+        errors << "namespace must be a bounded constant path" unless valid_namespace?(namespace)
+        refuse!(operation, errors) if errors.any?
+
+        @tool_name = canonical_segments.join(".")
+        refuse!(operation, [ "normalized MCP tool name must be 1 to 64 characters" ]) unless
+          @tool_name.length.between?(1, 64)
+
+        nested_constants = canonical_segments.map(&:camelize)
+        @class_name = ([ namespace ] + nested_constants).join("::")
+        @test_class_name = "#{@class_name}Test"
+        @class_modules = @class_name.split("::")[0...-1]
+        @class_leaf = @class_name.split("::").last
+        @tool_path = "app/tools/#{@class_name.underscore}.rb"
+        @test_path = "test/integration/#{@class_name.underscore}_test.rb"
+        @registration_line = %(register #{@class_name}, scopes: [ "mcp" ])
+      end
+
+      def normalize_name(value)
+        return unless value.is_a?(String) && value.bytesize.between?(1, 256)
+
+        source = value.gsub("::", "/")
+        return if source.start_with?("/") || source.end_with?("/") || source.include?("//")
+
+        segments = source.split("/")
+        normalized = segments.filter_map do |segment|
+          next unless NAME_SEGMENT_PATTERN.match?(segment)
+
+          candidate = segment.match?(/\A[A-Z]/) ? segment.underscore : segment.tr("-", "_")
+          candidate if CANONICAL_SEGMENT_PATTERN.match?(candidate)
+        end
+        normalized if normalized.length == segments.length
+      end
+
+      def valid_namespace?(value)
+        return false unless value.is_a?(String) && value.bytesize.between?(1, 255)
+        return false unless NAMESPACE_PATTERN.match?(value)
+
+        segments = value.split("::")
+        segments.length <= 8 && segments.all? { |segment| segment.bytesize <= 64 }
+      end
+
+      def deny_default?
+        options.fetch("deny_default")
+      end
+
+      def operation
+        behavior == :revoke ? "rollback" : "generation"
+      end
+
+      def refusal_subject = "Hitch tool"
+
+      def print_next_steps
+        say ""
+        if deny_default?
+          say "Generated and registered deny-default Hitch MCP tool #{@class_name}.", :green
+          say "It stays unavailable until you implement it."
+        else
+          say "Generated and registered Hitch MCP tool #{@class_name}.", :green
+          say "Verify it responds: bin/rails test #{@test_path}"
+        end
+      end
+    end
+  end
+end