rails-ai-bridge 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94459120e6365ac608ed9a403e16a622e7ef664b377f8585980827c28dd911f0
+  data.tar.gz: e3561760ceb930242a6d344ae3938dfdca49879639e7776a19cc2fa08adff4eb
+SHA512:
+  metadata.gz: c595b9b20dc56cef6adf370d931f06083137691cd5323dd8fe43615eba819eb7d725d5ee62160c0305fb311f3d2592ad767cd2eb8b69bfc3f075aae380b9209e
+  data.tar.gz: d6ee1293103eccc654bbed37f67b9deb022ecede51ee8bc4f4714db86f7f18d73a3ebe0054d86c6c8350107dd1bf6239520ff137c5b828faeb75152095c158bd

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,23 @@
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - "spec/fixtures/**/*"
+    - "vendor/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"

data/.ruby-version

@@ -0,0 +1 @@
+3.4.9

data/CHANGELOG.md

@@ -0,0 +1,259 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Shared runtime context provider** — MCP tools and `rails://...` resources now read through `RailsAiBridge::ContextProvider`, keeping cache invalidation and snapshot semantics aligned across both entry points.
+- **Explicit extension registries** — `config.additional_introspectors`, `config.additional_tools`, and `config.additional_resources` allow host apps or companion gems to extend the built-ins without patching core constants.
+- **HTTP transport Rack builder** — `RailsAiBridge::HttpTransportApp` centralizes HTTP MCP request handling for both standalone server mode and middleware auto-mount.
+- **Section-level context reads** — `ContextProvider.fetch_section` and `BaseTool.cached_section` let single-section tools avoid rebuilding or materializing the full snapshot path when unnecessary.
+- **Folder-level contributor docs** — key runtime folders now include local `README.md` guides for structure, boundaries, and extension points.
+- **Extensibility integration coverage** — specs now prove that a custom introspector, tool, and resource can be registered and used together from the host app configuration surface.
+
+### Changed
+
+- **Install generator messages** — the install flow now reports created vs unchanged files correctly and the generated initializer comments reflect the current preset sizes.
+- **Fingerprint reuse on invalidation** — context refresh reuses a single fingerprint snapshot per fetch cycle instead of scanning twice when cached context becomes stale.
+
+### Fixed
+
+- **Install generator output bug** — `generate_context` results are no longer iterated as raw hash pairs during install-time file generation.
+
+## [1.1.0] - 2026-03-20
+
+### Security
+
+- **HTTP MCP authentication** — Optional Bearer token via `config.http_mcp_token` or `ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]` (ENV wins when set). When a token is configured, `auto_mount` and `rails ai:serve_http` require `Authorization: Bearer <token>`.
+- **Production guards** — `config.auto_mount = true` in production raises at boot unless `config.allow_auto_mount_in_production = true` and a non-empty MCP token is set. `rails ai:serve_http` in production requires a token.
+- **`rails_search_code` allowlist** — `file_type` must be an allowed extension (default: `rb`, `erb`, `js`, `ts`, `jsx`, `tsx`, `yml`, `yaml`, `json`). Extra extensions: `config.search_code_allowed_file_types`. Unrestricted search uses only those extensions; ripgrep/Ruby paths also exclude common secret filenames (e.g. `.env*`, `*.key`, `*.pem`).
+- **Credentials metadata** — `credentials_keys` is omitted from config introspection and the `rails://config` MCP resource unless `config.expose_credentials_key_names = true`.
+
+## [1.0.0] - 2026-03-18
+
+### Changed
+
+- **First release as `rails-ai-bridge`** — Ruby gem and GitHub project renamed from `rails-ai-context`; public constant namespace is **`RailsAiBridge`**. Install with `rails generate rails_ai_bridge:install`. Host paths: `config/initializers/rails_ai_bridge.rb`, `config/rails_ai_bridge/overrides.md`, `.mcp.json` server key `rails-ai-bridge`, CLI `exe/rails-ai-bridge`. **Breaking:** no compatibility shim for the old gem name or paths.
+
+### Added
+
+- **`RailsAiBridge::Serializers::SharedAssistantGuidance`** — shared engineering rules, Rails performance pattern examples, optional **`config/rails_ai_bridge/overrides.md`** merge into compact Copilot + Codex, and Cursor `rails-engineering.mdc` body.
+- **Cursor `rails-engineering.mdc`** — `alwaysApply: true` engineering essentials + pointers to full `copilot-instructions.md` / `AGENTS.md` and MCP rules.
+- **Configuration** — `assistant_overrides_path`, `copilot_compact_model_list_limit` (default 5), `codex_compact_model_list_limit` (default 3); `0` lists no model names (MCP-only pointer).
+- **Install generator** — creates `config/rails_ai_bridge/overrides.md` stub and `overrides.md.example` when missing.
+
+### Fixed
+
+- **Overrides stub** — install stub uses `<!-- rails-ai-bridge:omit-merge -->`; overrides are **not** merged into Copilot/Codex until that line is removed.
+- **Consistent controller counts in compact output** — stack summaries use the controller introspector for the primary count (aligned with split rules); when routing lists more controller names than `app/controllers` classes, both counts are shown.
+
+### Changed
+
+- **Compact guidance** — `CLAUDE.md`, Copilot compact instructions, and `AGENTS.md` include a performance/security baseline and note that generated files are snapshots; `.codex/README.md` documents re-merging team rules.
+- **Copilot compact** — `.github/copilot-instructions.md` leads with **Engineering rules** before stack inventory; MCP section notes path-scoped files under `.github/instructions/` and `.cursor/rules/`.
+- **Copilot / Codex / `.cursorrules` order** — engineering rules → stack → optional repo-specific → performance + **Rails patterns** → trimmed models → MCP.
+- **Legacy `.cursorrules`** — same ordering; model list uses `copilot_compact_model_list_limit`.
+- **`rails-project.mdc`** — uses `ContextSummary.routes_stack_line`; caps gem categories; references `rails-engineering.mdc`.
+
+## [0.8.0] - 2026-03-19
+
+### Added
+
+- **OpenAI Codex support** via `AGENTS.md`, `.codex/README.md`, and `rails ai:context:codex`.
+- **Codex serializer integration** in the context file pipeline so `format: :all` now includes Codex output.
+
+### Fixed
+
+- **`rails_search_code` invalid regex handling** — the Ruby fallback path now returns a controlled error response instead of raising `RegexpError`.
+
+### Changed
+
+- **Fork metadata** — gemspec, `server.json`, README, CONTRIBUTING, SECURITY, and CODE_OF_CONDUCT now point to the maintained fork instead of upstream operational contacts.
+- **Security documentation** — clarified that MCP tools are read-only but may still expose sensitive application structure, especially over HTTP transport.
+- **Internal review summary** — translated `resume.md` to English and updated it to reflect the current fork, Codex support, compatibility notes, and security posture.
+
+## [0.7.1] - 2026-03-19
+
+### Added
+
+- **Full MCP tool reference in all context files** — every generated file (CLAUDE.md, .cursorrules, .windsurfrules, copilot-instructions.md) now includes complete tool documentation with parameters, detail levels, pagination examples, and usage workflow. Dedicated `rails-mcp-tools` split rule files added for Claude, Cursor, Windsurf, and Copilot.
+- **MCP Registry listing** — published to the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.crisnahine/rails-ai-context` via mcpb package type.
+
+### Fixed
+
+- **Schema version parsing** — versions with underscores (e.g. `2024_01_15_123456`) were truncated to the first digit group. Now captures the full version string.
+- **Documentation** — updated README (detail levels, pagination, generated file tree, config options), SECURITY.md (supported versions), CONTRIBUTING.md (project structure), gemspec (post-install message), demo_script.sh (all 17 generated files).
+
+## [0.7.0] - 2026-03-19
+
+### Added
+
+- **Detail levels on MCP tools** — `detail:"summary"`, `detail:"standard"` (default), `detail:"full"` on `rails_get_schema`, `rails_get_routes`, `rails_get_model_details`, `rails_get_controllers`. AI calls summary first, then drills down. Based on Anthropic's recommended MCP pattern.
+- **Pagination** — `limit` and `offset` parameters on schema and routes tools for apps with hundreds of tables/routes.
+- **Response size safety net** — Configurable hard cap (`max_tool_response_chars`, default 120K) on tool responses. Truncated responses include hints to use filters.
+- **Compact CLAUDE.md** — New `:compact` context mode (default) generates ≤150 lines per Claude Code's official recommendation. Contains stack overview, key models, and MCP tool usage guide.
+- **Full mode preserved** — `config.context_mode = :full` retains the existing full-dump behavior. Also available via `rails ai:context:full` or `CONTEXT_MODE=full`.
+- **`.claude/rules/` generation** — Generates quick-reference files in `.claude/rules/` for schema and models. Auto-loaded by Claude Code alongside CLAUDE.md.
+- **Cursor MDC rules** — Generates `.cursor/rules/*.mdc` files with YAML frontmatter (globs, alwaysApply). Project overview is always-on; model/controller rules auto-attach when working in matching directories. Legacy `.cursorrules` kept for backward compatibility.
+- **Windsurf 6K compliance** — `.windsurfrules` is now hard-capped at 5,800 characters (within Windsurf's 6,000 char limit). Generates `.windsurf/rules/*.md` for the new rules format.
+- **Copilot path-specific instructions** — Generates `.github/instructions/*.instructions.md` with `applyTo` frontmatter for model and controller contexts. Main `copilot-instructions.md` respects compact mode (≤500 lines).
+- **`rails ai:context:full` task** — Dedicated rake task for full context dump.
+- **Configurable limits** — `claude_max_lines` (default: 150), `max_tool_response_chars` (default: 120K).
+
+### Changed
+
+- Default `context_mode` is now `:compact` (was implicitly `:full`). Existing behavior available via `config.context_mode = :full`.
+- Tools default to `detail:"standard"` which returns bounded results, not unlimited.
+- All tools return pagination hints when results are truncated.
+- `.windsurfrules` now uses dedicated `WindsurfSerializer` instead of sharing `RulesSerializer` with Cursor.
+
+## [0.6.0] - 2026-03-18
+
+### Added
+
+- **Migrations introspector** — Discovers migration files, pending migrations, recent history, schema version, and migration statistics. Works without DB connection.
+- **Seeds introspector** — Analyzes db/seeds.rb structure, discovers seed files in db/seeds/, detects which models are seeded, and identifies patterns (Faker, environment conditionals, find_or_create_by).
+- **Middleware introspector** — Discovers custom Rack middleware in app/middleware/, detects patterns (auth, rate limiting, tenant isolation, logging), and categorizes the full middleware stack.
+- **Engine introspector** — Discovers mounted Rails engines from routes.rb with paths and descriptions for 23+ known engines (Sidekiq::Web, Flipper::UI, PgHero, ActiveAdmin, etc.).
+- **Multi-database introspector** — Discovers multiple databases, replicas, sharding config, and model-specific `connects_to` declarations. Works with database.yml parsing fallback.
+- **2 new MCP resources** — `rails://migrations`, `rails://engines`
+- **Migrations added to :standard preset** — AI tools now see migration context by default
+- **Doctor check** — New `check_migrations` diagnostic
+- **Fingerprinter** — Now watches `db/migrate/`, `app/middleware/`, and `config/database.yml`
+
+### Changed
+
+- Default `:standard` preset expanded from 8 to 9 introspectors (added `:migrations`)
+- Default `:full` preset expanded from 21 to 26 introspectors
+- Doctor checks expanded from 11 to 12
+- Static MCP resources expanded from 7 to 9
+
+## [0.5.2] - 2026-03-18
+
+### Fixed
+
+- **MCP tool nil crash** — All 9 MCP tools now handle missing introspector data gracefully instead of crashing with `NoMethodError` when the introspector is not in the active preset (e.g. `rails_get_config` with `:standard` preset)
+- **Zeitwerk dependency** — Changed from open-ended `>= 2.6` to pessimistic `~> 2.6` per RubyGems best practices
+- **Documentation** — Updated CONTRIBUTING.md, CHANGELOG.md, and CLAUDE.md to reflect Zeitwerk autoloading, introspector presets, and `.mcp.json` auto-discovery changes
+
+## [0.5.0] - 2026-03-18
+
+### Added
+
+- **Introspector presets** — `:standard` (8 core introspectors, fast) and `:full` (all 21, thorough) via `config.preset = :standard`
+- **`.mcp.json` auto-discovery** — Install generator creates `.mcp.json` so Claude Code and Cursor auto-detect the MCP server with zero manual config
+- **Zeitwerk autoloading** — Replaced 47 `require_relative` calls with Zeitwerk for faster boot and conventional file loading
+- **Automated release workflow** — GitHub Actions publishes to RubyGems via trusted publishing when a version tag is pushed
+- **Version consistency check** — Release workflow verifies git tag matches `version.rb` before publishing
+- **Auto GitHub Release** — Release notes extracted from CHANGELOG.md automatically
+- **Dependabot** — Weekly automated dependency and GitHub Actions updates
+- **README demo GIF** — Animated terminal recording showing install, doctor, and context generation
+- **SECURITY.md** — Security policy with supported versions and reporting process
+- **CODE_OF_CONDUCT.md** — Contributor Covenant v2.1
+- **GitHub repo topics** — Added discoverability keywords (rails, mcp, ai, etc.)
+
+### Changed
+
+- Default introspectors reduced from 21 to 8 (`:standard` preset) for faster boot; use `config.preset = :full` for all 21
+- New files auto-loaded by Zeitwerk — no manual `require_relative` needed when adding introspectors or tools
+
+## [0.4.0] - 2026-03-18
+
+### Added
+
+- **14 new introspectors** — Controllers, Views, Turbo/Hotwire, I18n, Config, Active Storage, Action Text, Auth, API, Tests, Rake Tasks, Asset Pipeline, DevOps, Action Mailbox
+- **3 new MCP tools** — `rails_get_controllers`, `rails_get_config`, `rails_get_test_info`
+- **3 new MCP resources** — `rails://controllers`, `rails://config`, `rails://tests`
+- **Model introspector enhancements** — Extracts `has_secure_password`, `encrypts`, `normalizes`, `delegate`, `serialize`, `store`, `generates_token_for`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `broadcasts_to` via source parsing
+- **Stimulus introspector enhancements** — Extracts `outlets` and `classes` from controllers
+- **Gem introspector enhancements** — 30+ new notable gems: monitoring (Sentry, Datadog, New Relic, Skylight), admin (ActiveAdmin, Administrate, Avo), pagination (Pagy, Kaminari), search (Ransack, pg_search, Searchkick), forms (SimpleForm), utilities (Faraday, Flipper, Bullet, Rack::Attack), and more
+- **Convention detector enhancements** — Detects concerns, validators, policies, serializers, notifiers, Phlex, PWA, encrypted attributes, normalizations
+- **Markdown serializer sections** — All 14 new introspector sections rendered in generated context files
+- **Doctor enhancements** — 4 new checks: controllers, views, i18n, tests (11 total)
+- **Fingerprinter expansion** — Watches `app/controllers`, `app/views`, `app/jobs`, `app/mailers`, `app/channels`, `app/javascript/controllers`, `config/initializers`, `lib/tasks`; glob now covers `.rb`, `.rake`, `.js`, `.ts`, `.erb`, `.haml`, `.slim`, `.yml`
+
+### Fixed
+
+- **YAML parsing** — `YAML.load_file` calls now pass `permitted_classes: [Symbol], aliases: true` for Psych 4 (Ruby 3.1+) compatibility
+- **Rake task parser** — Fixed `@last_desc` instance variable leaking between files; fixed namespace tracking with indent-based stack
+- **Vite detection** — Changed `File.exist?("vite.config")` to `Dir.glob("vite.config.*")` to match `.js`/`.ts`/`.mjs` extensions
+- **Health check regex** — Added word boundaries to avoid false positives on substrings (e.g. "groups" matching "up")
+- **Multi-attribute macros** — `normalizes :email, :name` now captures all attributes, not just the first
+- **Stimulus action regex** — Requires `method(args) {` pattern to avoid matching control flow keywords
+- **Controller respond_to** — Simplified format extraction to avoid nested `end` keyword issues
+- **GetRoutes nil guard** — Added `|| {}` fallback for `by_controller` to prevent crash on partial introspection data
+- **GetSchema nil guard** — Added `|| {}` fallback for `schema[:tables]` to prevent crash on partial schema data
+- **View layout discovery** — Added `File.file?` filter to exclude directories from layout listing
+- **Fingerprinter glob** — Changed from `**/*.rb` to multi-extension glob to detect changes in `.rake`, `.js`, `.ts`, `.erb` files
+
+### Changed
+
+- Default introspectors expanded from 7 to 21
+- MCP tools expanded from 6 to 9
+- Static MCP resources expanded from 4 to 7
+- Doctor checks expanded from 7 to 11
+- Test suite expanded from 149 to 247 examples with exact value assertions
+
+## [0.3.0] - 2026-03-18
+
+### Added
+
+- **Cache invalidation** — TTL + file fingerprinting for MCP tool cache (replaces permanent `||=` cache)
+- **MCP Resources** — Static resources (`rails://schema`, `rails://routes`, `rails://conventions`, `rails://gems`) and resource template (`rails://models/{name}`)
+- **Per-assistant serializers** — Claude gets behavioral rules, Cursor/Windsurf get compact rules, Copilot gets task-oriented GFM
+- **Stimulus introspector** — Extracts Stimulus controller targets, values, and actions from JS/TS files
+- **Database stats introspector** — Opt-in PostgreSQL approximate row counts via `pg_stat_user_tables`
+- **Auto-mount HTTP middleware** — Rack middleware for MCP endpoint when `config.auto_mount = true`
+- **Diff-aware regeneration** — Context file generation skips unchanged files
+- **`rails ai:doctor`** — Diagnostic command with AI readiness score (0-100)
+- **`rails ai:watch`** — File watcher that auto-regenerates context files on change (requires `listen` gem)
+
+### Fixed
+
+- **Shell injection in SearchCode** — Replaced backtick execution with `Open3.capture2` array form; added file_type validation, max_results cap, and path traversal protection
+- **Scope extraction** — Fixed broken `model.methods.grep(/^_scope_/)` by parsing source files for `scope :name` declarations
+- **Route introspector** — Fixed `route.internal?` compatibility with Rails 8.1
+
+### Changed
+
+- `generate_context` now returns `{ written: [], skipped: [] }` instead of flat array
+- Default introspectors now include `:stimulus`
+
+## [0.2.0] - 2026-03-18
+
+### Added
+
+- Named rake tasks (`ai:context:claude`, `ai:context:cursor`, etc.) that work without quoting in zsh
+- AI assistant summary table printed after `ai:context` and `ai:inspect`
+- `ENV["FORMAT"]` fallback for `ai:context_for` task
+- Format validation in `ContextFileSerializer` — unknown formats now raise `ArgumentError` with valid options
+
+### Fixed
+
+- `rails ai:context_for[claude]` failing in zsh due to bracket glob interpretation
+- Double introspection in `ai:context` and `ai:context_for` tasks (removed unused `RailsAiBridge.introspect` calls)
+
+## [0.1.0] - 2026-03-18
+
+### Added
+
+- Initial release
+- Schema introspection (live DB + static schema.rb fallback)
+- Model introspection (associations, validations, scopes, enums, callbacks, concerns)
+- Route introspection (HTTP verbs, paths, controller actions, API namespaces)
+- Job introspection (ActiveJob, mailers, Action Cable channels)
+- Gem analysis (40+ notable gems mapped to categories with explanations)
+- Convention detection (architecture style, design patterns, directory structure)
+- 6 MCP tools: `rails_get_schema`, `rails_get_routes`, `rails_get_model_details`, `rails_get_gems`, `rails_search_code`, `rails_get_conventions`
+- Context file generation: CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md, JSON
+- Rails Engine with Railtie auto-setup
+- Install generator (`rails generate rails_ai_bridge:install`)
+- Rake tasks: `ai:context`, `ai:serve`, `ai:serve_http`, `ai:inspect`
+- CLI executable: `rails-ai-bridge serve|context|inspect`
+- Stdio + Streamable HTTP transport support via official mcp SDK
+- CI matrix: Ruby 3.2/3.3/3.4 × Rails 7.1/7.2/8.0

data/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md — rails-ai-bridge development guide
+
+This is a Ruby gem that auto-introspects Rails applications and exposes their
+structure to AI assistants via the Model Context Protocol (MCP).
+
+## Architecture
+
+- `lib/rails_ai_bridge.rb` — Main entry point, public API (Zeitwerk autoloaded)
+- `lib/rails_ai_bridge/configuration.rb` — User-facing config with presets (:standard, :full)
+- `lib/rails_ai_bridge/introspector.rb` — Orchestrates sub-introspectors
+- `lib/rails_ai_bridge/introspectors/` — 27 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox, migrations, seeds, middleware, engines, multi_database)
+- `lib/rails_ai_bridge/tools/` — 9 MCP tools using the official mcp SDK
+- `lib/rails_ai_bridge/serializers/` — Output formatters (claude, claude_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON)
+- `lib/rails_ai_bridge/resources.rb` — MCP resources (static data AI clients read directly)
+- `lib/rails_ai_bridge/server.rb` — MCP server configuration (stdio + HTTP transports)
+- `lib/rails_ai_bridge/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint
+- `lib/rails_ai_bridge/fingerprinter.rb` — SHA256 file fingerprinting for cache invalidation
+- `lib/rails_ai_bridge/doctor.rb` — Diagnostic checks and AI readiness scoring
+- `lib/rails_ai_bridge/watcher.rb` — File watcher for auto-regenerating context files
+- `lib/rails_ai_bridge/engine.rb` — Rails Engine for auto-integration
+- `lib/generators/rails_ai_bridge/install/` — Install generator (creates .mcp.json, initializer, context files)
+
+## Key Design Decisions
+
+1. **Built on official mcp SDK** — not a custom protocol implementation
+2. **Zero-config** — Railtie auto-registers at boot, introspects without setup
+3. **Graceful degradation** — works without DB by parsing schema.rb as text
+4. **Read-only tools only** — all MCP tools are annotated as non-destructive
+5. **Dual output** — static files (CLAUDE.md) + live MCP server (stdio/HTTP)
+6. **Diff-aware** — context regeneration skips unchanged files
+7. **Per-assistant serializers** — each AI tool gets tailored output format
+8. **Zeitwerk autoloading** — files loaded on-demand, not all upfront
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (26) for power users
+10. **MCP auto-discovery** — `.mcp.json` generated by install generator
+11. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
+12. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.windsurf/rules/`, `.github/instructions/`
+
+## Testing
+
+```bash
+bundle exec rspec           # Run specs (364 examples)
+bundle exec rubocop         # Lint
+```
+
+Uses combustion gem for testing Rails engine behavior in isolation.
+
+## Conventions
+
+- Ruby 3.2+ features OK (pattern matching, etc.)
+- Follow rubocop-rails-omakase style
+- Every introspector returns a Hash, never raises (wraps errors in `{ error: msg }`)
+- MCP tools return `MCP::Tool::Response` objects per SDK convention
+- All tools prefixed with `rails_` per MCP naming best practices
+- `generate_context` returns `{ written: [], skipped: [] }` hash
+- Zeitwerk autoloads all files — no `require_relative` needed for new classes

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,44 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainer of this fork at **ismael.marin@gmail.com**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

data/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to rails-ai-bridge
+
+Thanks for your interest in contributing! This guide covers everything you need to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/igmarin/rails-ai-bridge.git
+cd rails-ai-bridge
+bundle install
+bundle exec rspec
+bundle exec rubocop --parallel
+```
+
+The test suite uses [Combustion](https://github.com/pat/combustion) to boot a minimal Rails app in `spec/internal/`. No external database required — tests run against an in-memory SQLite database.
+
+## Project Structure
+
+```
+lib/rails_ai_bridge/
+├── introspectors/     # 27 introspectors (schema, models, routes, etc.)
+├── tools/             # 9 MCP tools with detail levels and pagination
+├── serializers/       # Per-assistant formatters (claude, cursor, windsurf, copilot, JSON)
+├── server.rb          # MCP server setup (stdio + HTTP)
+├── engine.rb          # Rails Engine for auto-integration
+└── configuration.rb   # User-facing config (presets, context_mode, limits)
+```
+
+## Adding a New Introspector
+
+1. Create `lib/rails_ai_bridge/introspectors/your_introspector.rb` (auto-loaded by Zeitwerk)
+2. Implement `#initialize(app)` and `#call` → returns a Hash (never raises)
+3. Register it in `lib/rails_ai_bridge/introspector.rb` (the `INTROSPECTOR_MAP`)
+4. Add the key to the appropriate preset(s) in `Configuration::PRESETS` (`:standard` for core, `:full` for all)
+5. Write specs in `spec/lib/rails_ai_bridge/your_introspector_spec.rb`
+
+## Adding a New MCP Tool
+
+1. Create `lib/rails_ai_bridge/tools/your_tool.rb` inheriting from `BaseTool` (auto-loaded by Zeitwerk)
+2. Define `tool_name`, `description`, `input_schema`, and `annotations`
+3. Implement `def self.call(...)` returning `text_response(string)`
+4. Register in `Server::TOOLS`
+5. Write specs in `spec/lib/rails_ai_bridge/tools/your_tool_spec.rb`
+
+## Code Style
+
+- Follow `rubocop-rails-omakase` style (run `bundle exec rubocop`)
+- Ruby 3.2+ features welcome (pattern matching, etc.)
+- Every introspector must return a Hash and never raise — wrap errors in `{ error: msg }`
+- MCP tools return `MCP::Tool::Response` objects
+- All tools must be prefixed with `rails_` and annotated as read-only
+
+## Running Tests
+
+```bash
+bundle exec rspec              # Full test suite
+bundle exec rspec spec/lib/    # Just lib specs
+bundle exec rubocop --parallel # Lint check
+```
+
+## Pull Request Process
+
+1. Fork the repo and create your branch from `main`
+2. Add tests for any new functionality
+3. Ensure `bundle exec rspec` and `bundle exec rubocop` pass
+4. Update CHANGELOG.md under an `## [Unreleased]` section
+5. Open a PR with a clear title and description
+
+## Reporting Bugs
+
+Open an issue at https://github.com/igmarin/rails-ai-bridge/issues with:
+- Ruby and Rails versions
+- Gem version
+- Steps to reproduce
+- Expected vs actual behavior
+
+## Releasing to RubyGems (maintainers)
+
+Pre-flight checklist:
+
+1. **Name availability** — Confirm `rails-ai-bridge` is available (or owned by you) on [RubyGems](https://rubygems.org/gems/rails-ai-bridge).
+2. **Version** — `lib/rails_ai_bridge/version.rb` must match the Git tag (release workflow expects `v#{VERSION}`).
+3. **Changelog** — Add a `## [x.y.z]` section in `CHANGELOG.md` (release notes are extracted from it in CI).
+4. **Build locally** — `gem build rails-ai-bridge.gemspec` and smoke-test in a dummy Rails app (`rails generate rails_ai_bridge:install`, `rails ai:bridge`, `rails ai:serve`).
+5. **MFA** — RubyGems account must have MFA; `spec.metadata["rubygems_mfa_required"]` is already `"true"`.
+6. **Trusted publishing** — Prefer [OIDC trusted publishing](https://guides.rubygems.org/trusted-publishing/) with the existing `rubygems/release-gem@v1` workflow; configure the gem owner on RubyGems to trust this repository/workflow.
+7. **Secrets** — Avoid API keys in the repo; rely on trusted publishing or short-lived CI secrets.
+8. **MCP registry** — If you publish `server.json` to the MCP registry, coordinate the `name` field (`io.github.igmarin/rails-ai-bridge`) with registry requirements.
+9. **Post-release** — Verify `bundle add rails-ai-bridge` from RubyGems and that badges in the README resolve.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ismael G Marin Cabrera
+
+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.