hitch-rails 0.2.0

data/docs/operator/rate_limiting.md

@@ -0,0 +1,98 @@
+# Request admission for the Hitch MCP endpoint
+
+The MCP tools specification requires invocation rate limiting. Hitch provides
+one authenticated, endpoint-wide fixed-window limit shared across
+`server/discover`, `tools/list`, and `tools/call` for the validated principal
+and client.
+
+Hitch counts through your application's own cache store, the same way
+`ActionController::RateLimiting` does. It adds no service to your deployment.
+
+## Configuration
+
+Nothing is required. An application that already sets `config.cache_store` is
+already configured:
+
+```ruby
+# config/environments/production.rb
+config.cache_store = :solid_cache_store
+```
+
+The limit itself lives in the generated MCP initializer:
+
+```ruby
+config.mcp.request_limit = { to: 120, within: 1.minute }
+```
+
+To keep MCP admission out of your general cache, point it at a dedicated store:
+
+```ruby
+config.mcp.rate_limit_store = ActiveSupport::Cache::RedisCacheStore.new(
+  url: ENV["HITCH_MCP_REDIS_URL"]
+)
+```
+
+Any `ActiveSupport::Cache` store responding to `increment` is accepted.
+
+## What production requires
+
+Production boot fails closed when the resolved store cannot count one
+principal's requests across the processes serving them. Three stores are
+refused:
+
+| Store | Why it is refused |
+| --- | --- |
+| `:memory_store` | Per process; each worker keeps its own count |
+| `:null_store` | Retains nothing, so no window ever accumulates |
+| `:file_store` | Reads and writes without a lock, so counts are lost under concurrency |
+
+Development and test may use any of them. Where the store cannot count at all,
+admission is not enforced rather than failing every request — the same posture
+Rails takes, and safe because production refuses those stores at boot.
+
+## Accuracy
+
+Counting is approximate at window boundaries under concurrency, which is what a
+rate limit needs to be. Solid Cache on PostgreSQL is the loosest case: it can
+lose a few increments when a window's key is first created
+([rails/solid_cache#297](https://github.com/rails/solid_cache/pull/297)), so a
+burst at a boundary may admit a handful of extra calls before the limit engages.
+Redis and Memcached count exactly if you would rather they did.
+
+## Operational notes
+
+- Keys are HMAC digests of the validated principal type/id and client ID. Raw
+  principal IDs, client IDs, and bearer tokens never reach the store. Token
+  rotation cannot reset a caller's quota.
+- The quota deliberately spans every host scope and tool for that
+  principal/client. Per-tool quotas and distributed concurrency leases are
+  later work.
+- A rejection is `429` with a conservative `Retry-After` equal to the
+  configured window.
+- An error the store raises is `503` before request body parsing, Registry
+  work, SDK dispatch, or host behavior. Note that `RedisCacheStore` and Solid
+  Cache do not raise on a backend outage — they swallow the error and return
+  nil, so during an outage admission is not enforced. That is the same posture
+  `ActionController::RateLimiting` has on the same stores; if the limit must
+  hold through outages, use a store that raises.
+- Avoid an eviction policy that silently removes live quota keys. Eviction can
+  reset a caller's active window without producing a store error. If your
+  general cache is under memory pressure, give MCP admission a dedicated store.
+- One short-lived key exists per active principal/client window.
+
+## Deployment check
+
+Run migrations and the doctor in the same environment and with the same secret
+injection as the application processes:
+
+```sh
+bin/rails db:migrate
+bin/rails hitch:doctor
+```
+
+The `rate_limit_store` check drives the real configured store rather than
+describing it: it increments an isolated random `hitch:doctor:v1:*` key twice,
+asserts the counts are `1` then `2`, and removes the key. It never touches the
+`hitch:mcp:rate-limit:v1:*` application quota namespace. The check reports the
+store class, whether it is shared across processes, and the two probe counts;
+it emits no credentials or store message text.

data/docs/public_api/0.2.0.md

@@ -0,0 +1,322 @@
+# hitch-rails 0.2 public API
+
+This file documents the `0.2.0` compatibility surface — the gem's first
+public release. The authenticated `Hitch::MCP::Endpoint` is the only MCP
+endpoint: it is stateless POST/OPTIONS, and it performs no notification/202
+response shaping.
+
+For a confidential token exchange, `client_secret_basic` remains the only
+supported secret-bearing method. The form may repeat the same scalar
+`client_id` carried by the Basic username because the official Python MCP 2.0
+client emits that interoperable shape. Hitch rejects a body `client_secret`, a
+mismatched body ID, and duplicate or structured IDs before authorization-code
+consumption.
+
+The first configured `supported_scopes` entry is the base/default scope named
+by the initial MCP bearer challenge. Protected-resource metadata continues to
+advertise the complete supported set, and a known tool's 403 challenge names
+that tool's complete static scope requirement. This keeps the first grant least
+privileged while preserving explicit step-up.
+
+## Implemented surface
+
+`Hitch::Configuration#mcp` returns the one persistent
+`Hitch::MCP::Configuration` object owned by the top-level Hitch configuration
+with these runtime settings:
+
+- `enabled=` accepts `true` or `false` (default `false`) and is the one
+  explicit switch for the authenticated endpoint runtime. While it is false,
+  no other MCP setting is required or validated at boot.
+- `server_info=` accepts a static Hash with nonempty String `name` and
+  `version`, plus optional String `title` and `instructions`. It is validated
+  once at boot/prepare, alongside registry validation, and a malformed value
+  fails the boot rather than the first request; the request path reads the
+  validated frozen value. Unset, it defaults to the application's dasherized
+  name and version "1.0.0".
+- `max_request_bytes=` accepts a positive Integer and defaults to 1 MiB. The
+  current value is read for every request; overflow returns 413 before JSON
+  parsing.
+- `max_result_bytes=` accepts a positive Integer and defaults to 1 MiB. The
+  current value is read for every invocation; a Result whose exact serialized
+  JSON exceeds it becomes the generic tool error.
+- `scope_resolver=` accepts a callable with `principal:`, `access_token:`, and
+  `request:` keywords, or `nil` (the default), which resolves a `nil` scope.
+  A configured resolver runs exactly once per admitted request and returns
+  one opaque host scope object or `nil`. Raising resolvers fail closed with a
+  generic protocol internal error before registry or SDK work.
+- `request_limit=` accepts a mapping with positive Integer `to` and positive
+  whole-second Integer or `ActiveSupport::Duration` `within`. It defaults to
+  120 requests per 60 seconds and applies one fixed window across discovery,
+  listing, and calls for the validated principal/client.
+- `rate_limit_store=` accepts any `ActiveSupport::Cache` store responding to
+  `increment`, or `nil` to count through the application's own
+  `config.action_controller.cache_store`. Hitch adds no service to a deployment
+  that has none. `rate_limit_store` reads back the resolved store. Production
+  refuses a store that cannot count one principal's requests across the
+  processes serving them — `:memory_store`, `:null_store`, and `:file_store` —
+  and a raised runtime store error fails closed with HTTP 503. A store that
+  returns nil instead of raising (Redis and Solid Cache stores swallow backend
+  outages) admits without a limit, as Rails' own limiter does. Counting is
+  approximate at window boundaries under concurrency.
+
+Host MCP policy and behavior receive a fresh public `Hitch::MCP::Context` for
+every admitted request. It is a frozen envelope with readers for `principal`, `access_token`,
+`scope`, `granted_scopes`, `client_id`, `resource`, `request_id`, `remote_ip`,
+`user_agent`, `protocol_version`, and `meta`. Principal, token, and scope are
+opaque request-local references rather than objects Hitch claims to freeze.
+All scalar request values, granted scopes, and untrusted metadata are copied;
+metadata is recursively frozen. Granted scopes are captured from the validated
+token before the scope resolver runs, so scope resolution cannot rewrite the
+current request's static authorization. Client metadata never supplies
+authority.
+
+`config.mcp.registry=` accepts one nonempty String constant name. The named
+constant must resolve to a `Hitch::MCP::Registry` subclass, whose only admission
+path is `register ToolClass, scopes: [...]`. Registration stores the tool class
+name and copied static scopes, never the reloadable class object. A Rails
+`to_prepare` callback clears the prior snapshot, reconstantizes and validates
+the entire registry, and publishes one immutable MCP-name-sorted replacement.
+Failure raises and leaves the registry unavailable rather than serving a stale
+or partial snapshot.
+
+An auth-only adopter that leaves `config.mcp.enabled` false continues to boot
+unchanged; other MCP settings are inert without the switch. Setting
+`config.mcp.enabled = true` activates the endpoint runtime and requires a
+named `registry` at boot. Production additionally requires that the resolved
+admission store can count across processes.
+
+Registered classes subclass `Hitch::MCP::Tool` and declare `tool_name`,
+`description`, `input_schema`, optional `output_schema`, and optional
+`annotations`. Names use 1–64 ASCII letters, digits, underscores, dots, or
+dashes. Schemas are JSON Schema 2020-12 objects with same-document references
+only and fixed limits of 64 levels, 10,000 schema objects, and 1 MiB serialized
+bytes. A literal top-level `server_context` in `properties` or `required` is
+refused at boot; nested `server_context` data remains valid, and an actual
+top-level value is rejected at the verified call boundary even when a pattern
+or open schema would admit it. Tool annotations accept only `title` and the four MCP Boolean hint
+fields. Registry validation also rejects unsupported or duplicate scopes,
+duplicate MCP names, unnamed/missing/non-tool classes, and any subclass
+replacement of framework-owned `.call`.
+
+`.available_to?(context)` is the request-local, argument-free visibility and
+call-admission gate. Its framework default is `false`; hosts must explicitly
+return a Boolean from the current reloadable tool class. Availability runs
+before static scope filtering for list and call. A raise or non-Boolean result
+fails the whole request with generic `-32603` and no registry or scope detail.
+
+For `tools/list` and `server/discover`, Hitch constructs the SDK server from
+only registered tools that are available to the current context and whose
+static OAuth scopes are all granted. The order is MCP-name ascending, with
+`cacheScope: "private"`, `ttlMs: 0`, and `resultType: "complete"`. An unknown
+or unavailable call receives the same `-32602` shape. Only a registered,
+available tool may receive a 403 `insufficient_scope` challenge naming its
+complete required static scope set.
+
+After the SDK validates a call against the registered input schema, the final
+framework-owned `.call` copies the arguments into one recursively frozen Hash
+whose keys are Strings at every depth. `.authorize!(context, arguments:)` runs
+first and defaults to raising `Hitch::MCP::Forbidden`; its return value is
+ignored when it returns normally. `.perform(context, arguments:)` then receives
+the same Context and arguments object. Forbidden, unexpected policy failures,
+invalid non-JSON arguments, and host exceptions all return the same generic
+tool error, with no host work after policy denial and no exception message on
+the wire.
+
+`.perform` must return one exact `Hitch::MCP::Result`; Hashes, models,
+exceptions, SDK responses, and objects with serialization methods are rejected.
+`Result.text(string)` returns text, `Result.structured(value, text: nil)` accepts
+only recursively copied JSON values and requires the tool's registered output
+schema, and `Result.error(public_message)` returns the one explicit
+host-approved error message. Hitch validates structured output itself,
+measures `JSON.generate` of the final Result with an inclusive
+`max_result_bytes` boundary, and runs that as the one output-schema
+validation — the SDK's own result validation stays explicitly off. Invalid constructors or returns, missing/mismatched schemas,
+serialization failures, cap violations, and unexpected host errors all become
+the same generic tool error. Hitch reports a synthetic exception through
+`Rails.error` with only a fixed category, validated tool name, and, when request
+observation is active, Hitch's server-generated correlation ID. A client-supplied
+JSON-RPC ID is never logged. The original exception, arguments, result,
+principal, token, scope, and client metadata are never forwarded.
+
+`Hitch::MCP::Endpoint` is a public concern for a dedicated
+`ActionController::API` controller:
+
+```ruby
+class McpController < ActionController::API
+  include Hitch::MCP::Endpoint
+end
+```
+
+The host owns a catch-all route placed before the root engine mount:
+
+```ruby
+match "/mcp", to: "mcp#handle", via: :all
+mount Hitch::Engine => "/"
+```
+
+The concern owns stateless final-profile POST and OPTIONS handling. Its fixed
+order is raw Host, exact Origin, method, bearer authentication with active
+canonical audience and client binding, then authenticated fixed-window
+admission. It
+requires the request path/query to equal the canonical resource, validates
+Content-Type and both required Accept media types, reads at most the configured
+byte cap, rejects duplicate JSON members at any depth, validates modern request
+metadata and MCP headers, and dispatches one frozen request through one fresh
+SDK server. Forwarded headers never derive the challenge or server identity.
+
+The host-owned Registry is the packaged endpoint's only tool-admission path.
+
+`request.hitch_mcp` emits exactly once for every non-OPTIONS endpoint request.
+Its version-1 payload keys are `schema_version`, `request_id`, `method`,
+`tool_name`, `principal_type`, `principal_key`, `client_key`, `http_status`,
+`protocol_code`, `outcome`, `request_bytes`, `response_bytes`, and
+`duration_ms`. The request ID is framework-generated; principal/client keys are
+HMAC digests. Method and tool name are present only after their owning boundary
+validates them. `outcome` is a fixed HTTP/protocol category such as `complete`,
+`unauthorized`, `rate_limited`, `invalid_params`, or `internal_error`.
+
+`invocation.hitch_mcp` emits only when SDK schema validation and Hitch argument
+normalization reach a registered available Tool. Its version-1 keys are
+`schema_version`, `request_id`, `tool_name`, `availability`, `argument_policy`,
+`executed`, `result_category`, and `duration_ms`. Availability is `available`;
+argument policy is `allowed`, `denied`, or `failed`; result category is
+`success`, `explicit_error`, or `generic_error`. The request IDs correlate the
+two events. Neither event contains credentials, bodies, arguments, results,
+metadata, exception messages, or backtraces. Subscriber exceptions produce
+only a sanitized `Rails.error` report and do not alter the MCP response.
+
+`hitch:install` is public operational API. One run creates
+`config/initializers/hitch.rb`, a host-owned `ActionController::API` endpoint
+controller, the empty `McpToolRegistry` at `app/tools/mcp_tool_registry.rb`,
+and one routes insertion placing the `/mcp` route immediately before the
+`Hitch::Engine` mount. The `--controller-name` option accepts an explicit
+constant path ending in `Controller`. It refuses the entire install before
+writing when the controller name is invalid or an owned file or constant
+collides; an existing engine mount or host-owned `/mcp` route is skipped or
+warned about rather than duplicated. `bin/rails destroy hitch:install`
+reverses the install through the generator's revoke behavior — removing the
+generated files and the `/mcp` route it always writes, while the engine
+mount is deliberately left in place (with a status note) because a generated
+mount and a pre-existing host-owned one are indistinguishable without an
+install record. Beyond that, the host's version control is the rollback
+story.
+
+`hitch:tool NAME` is public operational API. NAME accepts valid snake-case,
+kebab-case, constant, and nested `/` or `::` segments. The default root
+namespace is `McpTools`; `--namespace Admin::McpTools` selects another valid
+constant path. Input segments normalize to one deterministic Ruby class, an
+`app/tools/` path, a Minitest integration-test path, and a 1–64 character
+dotted MCP name. A normalized file, class, or test class collision — or a
+missing Registry file — refuses the whole operation before writing.
+
+The generated Tool declares a closed empty input schema, all four MCP hint
+annotations, `.available_to? == true`, an `.authorize!` whose empty body
+allows the call and says so, and a `.perform` that returns
+`Hitch::MCP::Result.text`. The generator registers it in
+`McpToolRegistry` with `scopes: [ "mcp" ]`, and the generated integration
+test proves the tool is listed and responds through `post_mcp` over real
+HTTP. `--deny-default` generates the hardened variant instead —
+`.available_to? == false`, a raising `.authorize!`, a raising `.perform` —
+still registered, with a test asserting it stays hidden. `bin/rails destroy
+hitch:tool NAME` removes the generated files and the injected registration
+line; if the registration line was edited or reformatted it refuses the
+whole rollback before deleting anything, so a stranded registration can
+never break the next boot.
+
+`Hitch::MCP::TestHelper` is public test-only API loaded with
+`require "hitch/mcp/test_helper"`. `mcp_headers(token:, method:, name: nil,
+protocol_version: "2026-07-28")` returns exact Host, bearer, JSON, Accept,
+protocol, method, and conditional tool-name headers for the current configured
+resource. `post_mcp(method:, token:, params: {}, id: "hitch-test",
+client_info: nil, capabilities: {}, protocol_version: "2026-07-28")` copies and
+validates JSON test inputs, adds the final MCP metadata, posts one JSON-RPC 2.0
+request to the current resource path/query, and returns the ordinary Rails
+integration response. Invalid helper inputs raise `ArgumentError`; endpoint
+HTTP/protocol failures are not reclassified. Neither helper logs or places the
+bearer value in the request body. `mint_mcp_token(principal:, scopes:
+Hitch.configuration.supported_scopes, client_id: "hitch-test-client")` mints
+a real bearer token through the production authorization-code path
+(`create_authorization!` plus PKCE exchange) for any persisted principal
+record and returns the raw token `post_mcp` expects. Scopes outside
+`supported_scopes` raise `ArgumentError` rather than minting a grant the
+real flow could never issue.
+
+`bin/rails hitch:doctor` is public operational API. Its default human
+report and `HITCH_DOCTOR_FORMAT=json` machine report contain exactly these
+ordered IDs: `versions`, `configuration`, `resource_discovery`, `route_order`,
+`migrations`, `registry`, `hosts`, `origins`, and `rate_limit_store`.
+Every check names something the host can act on;
+gem-self-diagnosis (package integrity) lives in the repository's CI. The
+`versions` bounds come from the loaded gemspec. JSON uses schema
+`hitch.doctor.v1`; every check has `status`, stable `code`, `summary`, and
+bounded structural `details`.
+
+Statuses are `pass`, `warn`, `fail`, or `skip`. The task exits one only when at
+least one check fails, and prints every check before exiting. It performs
+internal read-only discovery requests and schema/route/Registry/package
+inspection. Its admission-store diagnostic increments a random
+`hitch:doctor:v1:*` key twice with a five-second expiry, asserts the counts are
+`1` then `2`, removes the key, and never uses application quota keys. Output
+omits exception messages, credentials, bodies, store credentials, and probe
+keys. There is no fix or repair
+mode. The exact operator contract is in `docs/operator/doctor.md`.
+
+`bin/rails hitch:tokens:issue PRINCIPAL=Model:id` issues a long-lived access
+token for a headless agent, and `Hitch::AccessToken.issue!(principal:,
+client_id:, client_name:, scopes:, expires_in:)` is the same call from a
+console. Both run the ordinary authorization-code exchange, so the row is an
+ordinary token: revocable, audience-bound, digest-at-rest. The task defaults
+to 90 days (capped at 3650 days), the first configured scope, and the
+`client_id` `hitch-cli`; `issue!` takes `expires_in` in seconds and otherwise
+applies `access_token_lifetime_seconds`. Disclosure writes once to a new
+`0600` file or an attached terminal, never to stdout.
+
+`Hitch::MCP::Protocol` is framework-owned: it names the protocol version and
+method set for Hitch's own use, and may change with the profile Hitch
+implements. Host test suites pin `Hitch::MCP::TestHelper::PROTOCOL_VERSION`
+instead.
+
+The operator tasks `hitch:doctor`, `hitch:cimd:check`,
+`hitch:clients:create_confidential`, `hitch:clients:rotate_secret`, and
+`Hitch::AccessToken.cleanup_expired!` are public and keep their names and
+arguments within 0.2.x.
+
+The gem directly depends on `mcp >= 1.2, < 2` and `json_schemer >= 2.4, < 3`.
+It declares no Redis dependency. Hitch's SDK adapter, verified
+request, runtime registry wrapper, and version-scoped response normalizer are private
+implementation details, not public constants or extension points. Context is
+the public exception; its construction remains framework-owned.
+
+`tools/call.params.arguments` may be omitted, as allowed by the protocol. When
+present it must be an object. Unsupported protocol versions keep Hitch's frozen
+`error.data.supportedVersions` field and additionally expose the official
+runner's `supported` list plus the echoed `requested` value.
+
+The conformance harness is test infrastructure, not runtime API. Its five
+fixture tools, separate runner-only missing-capability diagnostic, private
+bearer-file bridge, npm lock, and checked patch are never packaged. The gate
+runs only `server-stateless`, `http-header-validation`,
+`dns-rebinding-protection`, `json-schema-2020-12`, `tools-list`,
+`tools-call-simple-text`, and `tools-call-error`. It does not claim prompts,
+resources, caching, subscriptions, or all-server-suite conformance.
+
+The package/client harness is also repository test infrastructure, not
+runtime API. `bin/package-smoke` installs the exact built gem in a disposable
+Rails application and drives the full flow. `bin/package-smoke
+--automated-clients` adds one ephemeral Redis service, exercising
+`RedisCacheStore` as one supported admission backend, and the exhaustive
+official TypeScript/Python SDK 2.0.0 public/confidential matrix. The
+fixtures drive consent, PKCE/state/issuer validation, base-scope discovery,
+listing and calls, confidential-secret rotation, and scope step-up through
+documented host surfaces. Fixture inputs are private mode-0600 files; evidence
+contains no credentials. Product/model clients remain outside that automated
+claim and require separate approval.
+
+## Distribution status
+
+All `0.2.0.pre.1` through `0.2.0.pre.4` artifacts are internal checkpoints.
+`0.2.0.pre.4` was the first public-eligible prerelease, and publication was
+deferred so final `0.2.0` can become the first public RubyGems release. No
+pre.4 tag, GitHub release, RubyGems publication, or downloaded-gem evidence
+exists. Every future tag, GitHub release, or RubyGems publication still
+requires an explicit maintainer decision after its milestone gates pass.

data/docs/removing.md

@@ -0,0 +1,43 @@
+# Removing Hitch from a Rails application
+
+Removal is intentionally non-destructive. Unmounting the engine and removing
+the gem must not silently delete OAuth audit data or principal bindings.
+
+1. Disable new authorization and registration traffic at ingress. Set DCR off
+   before the final deploy.
+2. Revoke active Hitch tokens, or wait for their configured expiry if the MCP
+   endpoint has already been disabled.
+3. Stop jobs and schedules that call `Hitch::AccessToken.cleanup_expired!` or
+   Hitch rake tasks.
+4. Back up the `hitch_*` tables and decide their retention period under the
+   application's audit and privacy policy.
+5. Remove generated tools with
+   `bin/rails destroy hitch:tool NAME [--namespace Namespace]` while the gem
+   is installed — each removes its files and its registration line, refusing
+   the rollback if the registration line was edited — then run
+   `bin/rails destroy hitch:install` to remove the initializer, endpoint
+   controller, registry, and the `/mcp` route. Review anything you customized
+   in your version control history first; destroy reverses what the
+   generators wrote.
+6. Remove the `mount Hitch::Engine` line — destroy leaves it in place, since
+   it cannot tell a generated mount from one that pre-dates the install —
+   and any host controller inclusions of `Hitch::CorsSupport`.
+7. Remove the Gemfile entry and bundle again.
+
+`hitch:doctor` has no repair or uninstall mode. It is safe to use as a final
+read-only inventory before step 5, but its findings do not authorize deletion.
+The isolated diagnostic key is removed by the probe and has a five-second
+expiry; Hitch's ordinary rate-limit keys expire under their configured windows
+and require no uninstall sweep.
+
+Hitch does not ship a table-dropping removal migration. Keep the tables while
+old deployments, queued jobs, logs, or audit workflows may still refer to
+their IDs. If the application's owner later chooses deletion, create a host
+migration that names each `hitch_*` table explicitly, take a final backup, and
+review that irreversible operation independently. Do not reuse those table
+names for unrelated data.
+
+If the application may reinstall Hitch, retaining the tables and migration
+history is safer than dropping them. Reinstall the same or a forward-compatible
+version and run `bin/rails db:migrate`; never restore only part of the Hitch
+schema.

data/lib/generators/hitch/generator_guards.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hitch
+  module Generators
+    # Pre-flight guards shared by Hitch generators: check the destination
+    # before writing so a refused run leaves no partial install behind.
+    # Including generators define +refusal_subject+.
+    module GeneratorGuards
+      REGISTRY_PATH = "app/tools/mcp_tool_registry.rb"
+
+      private
+
+      def constant_collision?(name)
+        return false unless Object.const_defined?(name, false)
+        return true if File.expand_path(destination_root) == File.expand_path(Rails.root)
+
+        source = Object.const_source_location(name, false)&.first
+        source && File.expand_path(source).start_with?("#{File.expand_path(destination_root)}/")
+      rescue NameError
+        false
+      end
+
+      def destination_file?(relative_path)
+        File.file?(destination_path(relative_path))
+      end
+
+      def destination_path(relative_path)
+        File.expand_path(relative_path, destination_root)
+      end
+
+      def refuse!(operation, errors)
+        raise ::Thor::Error, "#{refusal_subject} #{operation} refused:\n- #{errors.join("\n- ")}"
+      end
+    end
+  end
+end

data/lib/generators/hitch/install/install_generator.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "rails/generators"
+require_relative "../generator_guards"
+
+module Hitch
+  module Generators
+    # One install: the initializer, the /mcp endpoint controller, an empty
+    # explicit tool registry, and the routes, in order. Migrations are
+    # auto-appended by the engine; run db:migrate after install.
+    #
+    # Usage:
+    #   bin/rails generate hitch:install
+    #   bin/rails destroy hitch:install
+    class InstallGenerator < ::Rails::Generators::Base
+      include Hitch::Generators::GeneratorGuards
+
+      # Declared explicitly so the command is always `hitch:install`,
+      # independent of generator-discovery ordering.
+      namespace "hitch:install"
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :controller_name,
+        type: :string,
+        default: "McpController",
+        desc: "Host controller constant to create (must end in Controller)"
+
+      INITIALIZER_PATH = "config/initializers/hitch.rb"
+      ROUTES_PATH = "config/routes.rb"
+      CONTROLLER_PATTERN = /\A[A-Z][A-Za-z0-9]*(?:::[A-Z][A-Za-z0-9]*)*Controller\z/
+      MCP_ROUTE_PATTERN = /["']\/?mcp\/?["']/
+
+      def self.exit_on_failure?
+        true
+      end
+
+      def install_or_revoke
+        prepare_identity!
+
+        if behavior == :revoke
+          remove_files
+          remove_routes
+          print_removal_steps
+        else
+          preflight!
+          create_files
+          add_routes
+          print_next_steps
+        end
+      end
+
+      private
+
+      def prepare_identity!
+        controller_name = options.fetch("controller_name")
+        unless CONTROLLER_PATTERN.match?(controller_name)
+          refuse!(operation, [ "controller name must be a constant path ending in Controller" ])
+        end
+
+        @controller_name = controller_name
+        @controller_modules = controller_name.split("::")[0...-1]
+        @controller_leaf = controller_name.split("::").last
+        @controller_path = "app/controllers/#{controller_name.underscore}.rb"
+        @route_target = controller_name.delete_suffix("Controller").underscore
+      end
+
+      def preflight!
+        errors = []
+        [ INITIALIZER_PATH, @controller_path, REGISTRY_PATH ].each do |path|
+          errors << "file collision: #{path}" if destination_file?(path)
+        end
+        errors << "constant collision: #{@controller_name}" if constant_collision?(@controller_name)
+        errors << "constant collision: McpToolRegistry" if constant_collision?("McpToolRegistry")
+        errors << "#{ROUTES_PATH} is missing a Rails.application.routes.draw block" unless
+          active_routes.include?(".routes.draw do")
+        refuse!("install", errors) if errors.any?
+      end
+
+      # Behavior-aware Thor actions: create in invoke, remove in revoke.
+      def create_files
+        template "initializer.rb", INITIALIZER_PATH
+        template "controller.rb.tt", @controller_path
+        template "registry.rb", REGISTRY_PATH
+      end
+      alias_method :remove_files, :create_files
+
+      # The /mcp route must precede the engine mount, so both go into one
+      # insertion at the top of the draw block.
+      def add_routes
+        active = active_routes
+        match_missing = !MCP_ROUTE_PATTERN.match?(active)
+        mount_missing = !active.include?("mount Hitch::Engine")
+
+        say_status :warn, "#{ROUTES_PATH} already routes /mcp; leaving it as is", :yellow unless match_missing
+        say_status :skip, "Hitch::Engine is already mounted", :yellow unless mount_missing
+        return unless match_missing || mount_missing
+
+        route(
+          [
+            (match_line if match_missing),
+            (mount_line if mount_missing)
+          ].compact.join("\n")
+        )
+      end
+
+      # Removes only the line this generator always writes. With no install
+      # record there is no way to tell a generated engine mount from one the
+      # host already had, and deleting a host-owned mount would take down its
+      # /oauth/* and discovery routes — so the mount is left in place and
+      # said so.
+      def remove_routes
+        active = active_routes
+        route(match_line) if active.include?(match_line)
+        return unless active.include?("mount Hitch::Engine")
+
+        say_status :skip,
+          "mount Hitch::Engine left in place (it may pre-date this install); remove it manually if unwanted",
+          :yellow
+      end
+
+      def match_line
+        %(match "/mcp", to: "#{@route_target}#handle", via: :all)
+      end
+
+      def mount_line
+        'mount Hitch::Engine => "/"'
+      end
+
+      def active_routes
+        return "" unless destination_file?(ROUTES_PATH)
+
+        File.binread(destination_path(ROUTES_PATH))
+          .each_line.reject { |line| line.lstrip.start_with?("#") }.join
+      end
+
+      def operation
+        behavior == :revoke ? "removal" : "install"
+      end
+
+      def refusal_subject = "Hitch"
+
+      # Removing the initializer leaves the engine's boot validation with no
+      # resource_uri, so the app will not start until the gem is gone too.
+      # Saying so here is the difference between a clean uninstall and an
+      # application that suddenly refuses to boot.
+      def print_removal_steps
+        say ""
+        say "hitch-rails files removed.", :green
+        say "The application will not boot until you also:"
+        say "  1. Remove the hitch-rails line from your Gemfile, then: bundle install"
+        say "  2. Roll back Hitch's tables if you no longer want them"
+        say "  3. Delete any tools you generated under app/tools/"
+        say "See docs/removing.md for the full order."
+      end
+
+      def print_next_steps
+        say ""
+        say "hitch-rails installed.", :green
+        say "Next steps:"
+        say "  1. Set resource_uri and brand_name in #{INITIALIZER_PATH}"
+        say "  2. Run: bin/rails db:migrate"
+        say "  3. Generate your first tool: bin/rails generate hitch:tool echo"
+      end
+    end
+  end
+end