coatepec 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 503cdd08a244ae010df42c9698c214d4a1e916969bae0f96ddaa62dfed2c2157
+  data.tar.gz: 54672230e5e1905f78f53d5614be4dccbcf0b5a9392fd3d0caae22dcf7d8c719
+SHA512:
+  metadata.gz: f33a3b662004ab4aaba6d80ade9176952c90730ebe44a009f4f3443db5888c56b7fd8094b87c17b7be8a29519f7f067c2c6efcdb796249a4da3bc81945b236af
+  data.tar.gz: 8bfe0dccc1861c8b8923a8e049898ad8ead99da9febc5b85274914dad61ac52f06c3d5726e14d05b097e425e9a6c98eba1e3bca3bc98a51b6ea1227fb4b96bf7

data/.rspec

@@ -0,0 +1,4 @@
+--format documentation
+--color
+--require spec_helper
+--exclude-pattern "spec/fixtures/**/*_spec.rb"

data/.rubocop.yml

@@ -0,0 +1,28 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  Exclude:
+    - "spec/fixtures/**/*"
+    # CI's `bundler-cache: true` installs gems into ./vendor/bundle (inside
+    # the repo tree, for caching) rather than the system gem home. Without
+    # this, RuboCop recursively scans installed gems too and can pick up a
+    # dependency's own dev-only .rubocop.yml (e.g. rbs ships one declaring
+    # plugins we don't have installed), crashing with a LoadError.
+    - "vendor/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Metrics/BlockLength:
+  # RSpec's describe/context/it DSL naturally produces long blocks; this is the
+  # standard exclusion used by rubocop-rspec's own default config. inherit_mode
+  # merges this onto (rather than replacing) RuboCop's own default Exclude list
+  # for this cop, which already exempts **/*.gemspec -- a plain `Exclude:` here
+  # would silently drop that default exemption and flag coatepec.gemspec.
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "spec/**/*_spec.rb"

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 0.4.0
+
+- Add `enums` to `rails_model`'s output, sourced from ActiveRecord's own
+  `defined_enums` API (pure in-memory, no DB query, no eval). Attempted
+  unconditionally, unlike `columns`/`associations`, since enum declarations
+  don't need a real table.
+
+## 0.3.0
+
+- Add `rails_routes` and `rails_model` MCP tools: bounded, filterable route
+  listing and ActiveRecord schema/association/validator introspection,
+  both running synchronously in the existing warm test worker (no
+  fork/spawn). `rails_model` is restricted to `ActiveRecord::Base`
+  descendants, resolved only via `safe_constantize` against a validated
+  constant-name pattern -- no eval, no arbitrary method dispatch.
+- The warm worker now forces Rails' reload-checking on at boot (overriding
+  the target app's own `test.rb`, which disables it by default) and wraps
+  every dispatched command in `Rails.application.reloader.wrap`, so edited
+  model files no longer serve stale metadata without a worker restart.
+  Benefits `rails_runtime_status` and `rails_spec_run`'s fork path too.
+  Note that this applies process-wide: `rails_spec_run` also executes specs
+  under the forced `enable_reloading`/`cache_classes` settings rather than
+  the app's own `test.rb` values. The file watcher is pinned to the polling
+  `ActiveSupport::FileUpdateChecker` at the same time, so an app configuring
+  `ActiveSupport::EventedFileUpdateChecker` doesn't get `listen` threads
+  started inside the warm worker (and inside the fork guard's baseline).
+
+## 0.2.0
+
+- Add an opt-in, guarded `Process.fork` strategy for macOS
+  (`macos_fork: true` in a project's `.coatepec.yml`), closing most of the
+  warm-worker performance gap that previously only benefited Linux. Guards
+  a live thread-count check and a loaded-gem denylist against fork-unsafety,
+  and transparently falls back to a fresh spawn -- with the remaining
+  timeout budget, and the crashed child's stderr for diagnosis -- if a
+  guard fails or the forked child crashes. `rails_spec_run` results gain
+  an `execution_mode` field when this strategy is in play.
+
+## 0.1.0
+
+- Initial implementation: `rails_spec_run` and `rails_runtime_status` MCP tools,
+  a warm Rails test worker with fork (Linux) / spawn (macOS) isolation per
+  RSpec run, and a path-selector allowlist as the security boundary.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Enrique Mogollan
+
+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,164 @@
+# Coatepec
+
+Coatepec gives coding agents a bounded way to run targeted RSpec examples
+against a Rails application, over MCP, without exposing a general Rails
+console.
+
+## Quickstart
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "coatepec", require: false
+end
+```
+
+```bash
+bundle install
+bundle exec coatepec --version
+```
+
+Configure your MCP client to run `bundle exec coatepec --root /absolute/path/to/app`
+from the Rails application's own bundle.
+
+With the [Claude Code CLI](https://docs.claude.com/en/docs/claude-code),
+from the Rails app's own root:
+
+```bash
+claude mcp add coatepec --scope project -- bundle exec coatepec --root .
+```
+
+That writes a project-scoped `.mcp.json` you can commit so the whole team
+gets it. For any other MCP-compatible client, or to write it by hand, the
+same thing looks like:
+
+```json
+{
+  "mcpServers": {
+    "coatepec": {
+      "command": "bundle",
+      "args": ["exec", "coatepec", "--root", "."]
+    }
+  }
+}
+```
+
+## Architecture
+
+```text
+MCP client
+    |
+    | JSON-RPC over stdio
+    v
+Coatepec parent (Rails-free)
+    `-- private NDJSON --> test worker (Rails "test", booted lazily, kept warm)
+                              |-- Linux:  Process.fork  --> isolated RSpec child
+                              `-- macOS:  Process.spawn --> fresh RSpec process (default)
+                                          Process.fork, guarded --> opt-in, see Configuration
+```
+
+## Configuration
+
+An optional `.coatepec.yml` at the target Rails app's root enables
+per-project settings:
+
+```yaml
+macos_fork: true                     # opt into forking on macOS (see below)
+macos_fork_unsafe_gems: [some_gem]   # extends the built-in fork-unsafe denylist
+```
+
+A missing file means every setting takes its default -- this file is never
+required.
+
+### macOS fork (experimental, opt-in)
+
+On macOS, `rails_spec_run` normally spawns a fresh `bundle exec rspec`
+process per call, re-booting Rails every time -- the warm-worker speedup
+described above only applies on Linux by default. Setting `macos_fork:
+true` lets Coatepec attempt `Process.fork` on macOS too, reusing the warm
+boot the way Linux does.
+
+This is opt-in because forking a process with native extensions loaded
+isn't universally safe. Before each fork, Coatepec checks the worker's
+live thread count against its post-boot baseline and its loaded gems
+against a denylist, falling back to a fresh spawn for that one call if
+either check looks risky. The built-in denylist ships empty -- no single
+gem has been confirmed as the culprit yet -- so the guard is effectively
+thread-count-only until a project adds its own
+`macos_fork_unsafe_gems`. If a fork is attempted and the child crashes
+anyway, Coatepec transparently retries via spawn and returns that result
+-- fork stays enabled for later calls. Every `rails_spec_run` result
+includes an `execution_mode` field (`fork`, `spawn_fallback`, or
+`spawn_after_crash`) so you can see which path actually ran for a given
+call; `spawn_after_crash` results also carry the crashed fork's own stderr
+under `crashed_fork_stderr` so the crash can be diagnosed.
+
+## Tools
+
+| Tool | Input | Notes |
+|---|---|---|
+| `rails_spec_run` | `paths: string[1..100]`, `example?`, `seed?`, `fail_fast?`, `timeout_seconds?` (1..900, default 120) | Isolated per run; output capped at 256 KiB per stream |
+| `rails_runtime_status` | `{}` | Reports Ruby/Rails versions, worker PID, boot_id, lifecycle state |
+| `rails_routes` | `query?`, `limit?` (1..200, default 50), `offset?` | Case-insensitive filter across name/verb/path/controller/action |
+| `rails_model` | `name` (constant path, e.g. `Widget` or `Admin::Widget`) | ActiveRecord models only; columns, associations, validators, enums -- no row data |
+
+The warm test worker forces Rails' reload-checking on for its own boot,
+regardless of the target app's own `test.rb` setting (which disables it by
+default) -- so editing a model file takes effect on the next tool call
+without needing to restart Coatepec. This is not limited to metadata reads:
+because the setting is applied to the whole worker process, `rails_spec_run`
+also executes your specs with `enable_reloading = true` and `cache_classes =
+false` rather than whatever your own `config/environments/test.rb` asks for
+(the file watcher is additionally pinned to the polling
+`ActiveSupport::FileUpdateChecker`, so no `listen` threads are started in the
+worker). For most apps this is invisible, but if you ever see behavior differ
+between Coatepec and your own `bundle exec rspec`, this is the first thing to
+suspect.
+
+## Security boundary
+
+No eval, console, SQL/record access, shell, Rake, or file-write tool. Spec
+selectors must resolve inside an allowed spec root (`spec/`, `packs/*/spec/`,
+`engines/*/spec/`, `gems/*/spec/`); absolute paths, `..`, symlink escapes,
+non-`_spec.rb` files, and more than 100 selectors are rejected. RSpec still
+executes application-controlled code; only run Coatepec against a trusted
+checkout.
+
+### Compared to Rails Active MCP
+
+[Rails Active MCP](https://github.com/GoodPie/rails-active-mcp) is a
+different MCP server for Rails apps built around a `console_execute` tool:
+arbitrary Ruby runs in your Rails console, gated by pattern-based
+"dangerous operation" detection (blocking things like mass deletions,
+`eval`, or raw SQL) rather than by not offering code execution at all --
+sophisticated bypasses of a denylist like that are always possible in
+principle.
+
+Coatepec takes the opposite approach: there's no eval, console, or SQL
+tool to begin with. `rails_spec_run` only ever executes RSpec files that
+already exist under the app's own allowed spec roots, and `rails_routes`/
+`rails_model` only ever call structured, read-only Rails APIs
+(`Rails.application.routes.routes`, `ActiveRecord` reflection) -- never
+`eval`, `const_get` on unvalidated input, or arbitrary method dispatch. If
+you genuinely need a Rails console over MCP, Rails Active MCP is built for
+that; Coatepec is for teams who want an agent to run specs and read
+structure without ever handing it a REPL.
+
+## Compatibility
+
+Ruby `>= 3.2`, Rails `>= 7.1, < 8.2`. CI tests three lanes: Rails 8.1 on
+Linux (primary), Rails 7.1 on Linux (compat), and Rails 8.1 on macOS (which
+is where the guarded-fork path above actually forks).
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec:unit          # fast, no Rails boot
+bundle exec rake spec:integration   # boots the fixture Rails app
+bundle exec rake                    # full suite + rubocop
+```
+
+## License
+
+Coatepec is available under the MIT License. See `LICENSE.txt`.

data/Rakefile

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :spec do
+  desc "Run unit specs (fast, no Rails boot)"
+  RSpec::Core::RakeTask.new(:unit) do |t|
+    t.pattern = "spec/unit/**/*_spec.rb"
+  end
+
+  desc "Run integration specs (boots the fixture Rails app)"
+  RSpec::Core::RakeTask.new(:integration) do |t|
+    t.pattern = "spec/integration/**/*_spec.rb"
+  end
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/coatepec

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "coatepec/mcp"
+require "coatepec/cli"
+
+Coatepec::CLI.run(ARGV)

data/exe/coatepec-worker

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "coatepec"
+
+# Preserve a real handle to the OS stdout fd for the private NDJSON
+# protocol before Rails boot has a chance to write banners/logs to it.
+protocol_output = $stdout.dup
+$stdout = $stderr
+
+project_root = ARGV[0] || Dir.pwd
+Coatepec::Worker::Server.new(project_root, input: $stdin, protocol_output: protocol_output).run

data/lib/coatepec/cli.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Coatepec
+  # Entry point for the `coatepec` executable: parses `--root`/`--debug`/
+  # `--version`/`--help`, then runs the MCP server over stdio.
+  class CLI
+    def self.run(argv)
+      options = parse(argv)
+      project = Coatepec::Project.new(options[:root] || Dir.pwd)
+      worker_manager = Coatepec::WorkerManager.new(project)
+      server = Coatepec::MCP.build_server(project: project, worker_manager: worker_manager)
+      ::MCP::Server::Transports::StdioTransport.new(server).open
+    rescue Coatepec::Error => e
+      warn "coatepec: #{e.code}: #{e.message}"
+      exit 1
+    end
+
+    def self.parse(argv)
+      options = { root: nil, debug: false }
+      remaining = argv.dup
+      while (arg = remaining.shift)
+        apply_flag!(options, arg, remaining)
+      end
+      options
+    end
+
+    def self.apply_flag!(options, arg, remaining)
+      case arg
+      when "--root" then options[:root] = remaining.shift
+      when "--debug" then (options[:debug] = true
+                           ENV["COATEPEC_DEBUG"] = "1")
+      when "--version" then (puts Coatepec::VERSION
+                             exit 0)
+      when "--help" then (puts "Usage: coatepec --root PATH [--debug]"
+                          exit 0)
+      end
+    end
+    private_class_method :apply_flag!
+  end
+end

data/lib/coatepec/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Coatepec
+  # Structured error carrying a stable machine-readable `code` (and optional
+  # `details`) that MCP tool handlers translate into JSON error responses.
+  class Error < StandardError
+    attr_reader :code, :details
+
+    def initialize(code, message = nil, details: {})
+      @code = code
+      @details = details
+      super(message || code.to_s)
+    end
+  end
+end

data/lib/coatepec/introspection/model.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Returns bounded ActiveRecord schema and class metadata for a single
+    # model, for the rails_model MCP tool. No records, no SQL beyond schema
+    # reflection, no method dispatch on the resolved class beyond pure
+    # introspection APIs.
+    class Model
+      NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
+      MAX_ITEMS = 200
+      EMPTY_TABLE_METADATA = { table_name: nil, primary_key: nil, columns: [] }.freeze
+
+      def initialize(name)
+        @name = name
+      end
+
+      def call
+        validate_name!
+        klass = resolve!
+        validate_active_record!(klass)
+        build_metadata(klass)
+      end
+
+      private
+
+      # An abstract class (e.g. ApplicationRecord) has no real table, so
+      # table_name/primary_key/columns all raise if called against it --
+      # report empty/nil table data instead of crashing. Validators aren't
+      # table-dependent, so those are always attempted.
+      def build_metadata(klass)
+        # abstract_class? is a plain attr_accessor-backed predicate that is
+        # never assigned on concrete subclasses -- on Rails 7.1 it returns
+        # nil (not false) in that case, while Rails 8.1 returns false.
+        # Normalize to a genuine Boolean so JSON output is version-stable.
+        abstract = klass.abstract_class? || false
+        table = abstract ? EMPTY_TABLE_METADATA : table_metadata(klass)
+        {
+          name: klass.name, table_name: table[:table_name], primary_key: table[:primary_key],
+          abstract_class: abstract, columns: table[:columns],
+          associations: abstract ? [] : associations_for(klass),
+          validators: validators_for(klass),
+          # enum declarations are pure in-memory class metadata (populated
+          # when the `enum` macro runs in the class body) -- unlike columns
+          # and associations, they need no DB connection or real table, so
+          # this is attempted unconditionally, the same way validators are.
+          enums: enums_for(klass)
+        }
+      end
+
+      # A concrete model can still name a table that isn't there: a checkout
+      # whose test database is behind on migrations, a view-backed model, a
+      # model living in a database this process isn't connected to. That is
+      # deliberately *not* folded into the abstract-class handling above --
+      # an abstract class declares "I have no table", so empty column data is
+      # the truthful answer for it, whereas a missing table is a real
+      # mismatch the caller needs told about. Reporting it as a table with
+      # zero columns would read as "this model has no columns", which is a
+      # lie. It gets its own structured code instead of escaping as the
+      # server's catch-all :internal_error. The exception's own message is
+      # not interpolated: it carries driver-specific SQL text.
+      def table_metadata(klass)
+        { table_name: klass.table_name, primary_key: klass.primary_key, columns: columns_for(klass) }
+      rescue ::ActiveRecord::StatementInvalid
+        raise Coatepec::Error.new(
+          :table_not_found,
+          "#{@name}'s table (#{klass.table_name}) does not exist or could not be read"
+        )
+      end
+
+      def validate_name!
+        return if @name.is_a?(String) && NAME_PATTERN.match?(@name)
+
+        raise Coatepec::Error.new(:invalid_model_name, "#{@name.inspect} is not a valid constant name")
+      end
+
+      def resolve!
+        ::ActiveSupport::Inflector.safe_constantize(@name) ||
+          raise(Coatepec::Error.new(:model_not_found, "#{@name} could not be resolved"))
+      end
+
+      def validate_active_record!(klass)
+        return if klass.is_a?(Class) && klass < ::ActiveRecord::Base
+
+        raise Coatepec::Error.new(:not_active_record_model, "#{@name} is not an ActiveRecord model")
+      end
+
+      def columns_for(klass)
+        klass.columns.first(MAX_ITEMS).map do |column|
+          { name: column.name, type: column.type.to_s, sql_type: column.sql_type, null: column.null,
+            default: column.default }
+        end
+      end
+
+      def associations_for(klass)
+        klass.reflect_on_all_associations.first(MAX_ITEMS).map { |assoc| build_association_data(assoc) }
+      end
+
+      def build_association_data(assoc)
+        {
+          name: assoc.name.to_s,
+          macro: assoc.macro.to_s,
+          class_name: association_class_name(assoc),
+          foreign_key: assoc.foreign_key.to_s,
+          through: assoc.through_reflection&.name&.to_s,
+          polymorphic: assoc.polymorphic? || false
+        }
+      end
+
+      # A polymorphic belongs_to has no single fixed target class (assoc.klass
+      # raises ArgumentError for those), and a reflection whose class_name
+      # points at a constant that doesn't exist raises NameError. Both are
+      # legitimate, introspectable states -- report class_name: nil rather
+      # than letting either crash the whole call.
+      def association_class_name(assoc)
+        return nil if assoc.polymorphic?
+
+        assoc.klass.name
+      rescue NameError, ArgumentError
+        nil
+      end
+
+      def validators_for(klass)
+        klass.validators.first(MAX_ITEMS).map do |validator|
+          {
+            name: validator.class.name,
+            attributes: validator.attributes.map(&:to_s),
+            options: SafeOptions.call(validator.options)
+          }
+        end
+      end
+
+      def enums_for(klass)
+        klass.defined_enums.first(MAX_ITEMS).map do |name, values|
+          { name: name, values: values.first(MAX_ITEMS).to_h }
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/introspection/routes.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Returns a bounded, filterable list of the target Rails app's routes,
+    # for the rails_routes MCP tool. Reads Rails.application.routes.routes
+    # only -- no console, no request dispatch.
+    class Routes
+      MAX_LIMIT = 200
+      DEFAULT_LIMIT = 50
+
+      def initialize(query: nil, limit: DEFAULT_LIMIT, offset: 0)
+        @query = query
+        @limit = [limit || DEFAULT_LIMIT, MAX_LIMIT].min
+        @offset = offset || 0
+      end
+
+      def call
+        matched = filtered_items
+        {
+          items: matched[@offset, @limit] || [],
+          matched: matched.size,
+          limit: @limit,
+          offset: @offset
+        }
+      end
+
+      private
+
+      def filtered_items
+        items = all_items
+        return items unless @query
+
+        query_downcased = @query.downcase
+        items.select { |item| item.values.compact.any? { |v| v.to_s.downcase.include?(query_downcased) } }
+      end
+
+      def all_items
+        self.class.rails_routes.map do |route|
+          defaults = route.defaults
+          {
+            name: route.name&.to_s,
+            verb: route.verb.to_s,
+            path: route.path.spec.to_s,
+            controller: defaults[:controller]&.to_s,
+            action: defaults[:action]&.to_s
+          }
+        end
+      end
+
+      # Isolated as a class method purely so unit tests can stub it without
+      # booting Rails -- Rails.application.routes.routes is otherwise only
+      # reachable with a real, booted application.
+      # rubocop:disable Lint/IneffectiveAccessModifier
+      def self.rails_routes
+        Rails.application.routes.routes
+      end
+      # rubocop:enable Lint/IneffectiveAccessModifier
+    end
+  end
+end

data/lib/coatepec/introspection/safe_options.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Filters an ActiveRecord validator's `options` hash down to genuinely
+    # primitive values before it's serialized as rails_model output.
+    # Validator options can carry arbitrary Ruby objects (Proc for `if:`/
+    # `unless:`, Regexp for `with:`, etc.) that must never be JSON-serialized
+    # as-is -- Proc#to_s leaks the target app's absolute source file path
+    # and line number. Only genuinely primitive values pass through;
+    # anything else is silently dropped.
+    module SafeOptions
+      module_function
+
+      def call(options)
+        options.filter_map do |key, value|
+          safe_value = value_for(value)
+          [key.to_s, safe_value] unless safe_value.nil? && !value.nil?
+        end.to_h
+      end
+
+      def value_for(value)
+        case value
+        when String, Numeric, TrueClass, FalseClass, NilClass
+          value
+        when Symbol
+          value.to_s
+        when Array
+          array_value_for(value)
+        end
+      end
+
+      # Symbol *elements* are stringified exactly as a bare Symbol value is
+      # above: `inclusion: { in: %i[draft published] }` is one of the most
+      # common option shapes in Rails, and dropping the whole `in:` key for it
+      # while keeping the single-Symbol equivalent would be arbitrary. An
+      # array still holding anything non-primitive after that is dropped
+      # whole -- a mixed array's non-primitive members can't be silently
+      # elided without misrepresenting the option.
+      def array_value_for(value)
+        stringified = value.map { |element| element.is_a?(Symbol) ? element.to_s : element }
+        stringified.all? { |element| element.is_a?(String) || element.is_a?(Numeric) } ? stringified : nil
+      end
+    end
+  end
+end

data/lib/coatepec/mcp/response.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+require "mcp"
+
+module Coatepec
+  module MCP
+    # Builds the pretty-printed JSON `{ok: true, data:, meta:}` / `{ok: false,
+    # error:}` envelope that every Coatepec tool response wraps in a single
+    # text content block.
+    module Response
+      # Per-stream caps in Spec::Result bound stdout/stderr, but the fully
+      # assembled envelope (500 examples with long descriptions) can still
+      # exceed what an MCP client will accept, so cap it here -- the single
+      # place every tool response is built.
+      MAX_RESPONSE_BYTES = 1024 * 1024
+
+      module_function
+
+      def ok(data:, meta: {})
+        text = JSON.pretty_generate(ok: true, data: data, meta: meta)
+        return oversized_response if text.bytesize > MAX_RESPONSE_BYTES
+
+        ::MCP::Tool::Response.new([{ type: "text", text: text }])
+      end
+
+      def error(err)
+        payload = {
+          ok: false,
+          error: { code: err.code.to_s, message: err.message, details: err.details }
+        }
+        ::MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(payload) }], error: true)
+      end
+
+      def oversized_response
+        error(Coatepec::Error.new(:response_too_large, "Result exceeds the 1 MiB response limit"))
+      end
+    end
+  end
+end