轨道透镜

![CI](https://github.com/ei-nakamura/rails-lens/actions/workflows/ci.yml) ](https://badge.fury.io/py/rails-lens) ](https://pypi.org/project/rails-lens/)

MCP服务器，揭示了AI编码工具的隐含Rails依赖关系。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\ 亲爱的RAILS开发者们，

您所有的隐藏回调都属于我们。\ 你所有隐含的担忧都属于我们。\ 你所有的猴子补丁方法都属于我们。

你没有机会生存——编写你的代码。

--轨道透镜\ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

概述

rails透镜是一个MCP（模型上下文协议）服务器，用于提取和公开 Ruby on Rails应用程序结构到人工智能编码工具，如Claude Code和Cursor。它帮助AI工具理解Rails的隐式依赖关系，关注点和动态方法生成。

19工具 旨在让AI助手深入了解Rails应用程序：

第1-4阶段（核心反思）

具有回调、关联和验证的内省模型
在代码库中查找对方法或类的所有引用
跟踪完整的回调链，包括继承的和关注注入的钩子
生成模型之间的依赖关系图
转储数据库模式和路由
分析共同关注的问题
管理自检缓存

第5-8阶段（高级分析）

解释方法解析顺序（MRO）和祖先链
Introspect Gem注入方法和回调
分析更改列或方法的影响
将模型和方法映射到其测试文件
检测死代码（未使用的方法、回调、作用域）
检测模型之间的循环依赖关系
从脂肪模型中识别问题提取候选者
跟踪从HTTP请求到数据库的数据流
提供迁移背景和安全警告

第9-10阶段（屏幕映射）

将屏幕映射到源文件（模板、部分、助手、模型）
通过影响分析将源文件反向映射到受影响的屏幕
自动生成全屏清单（Markdown/JSON）

需求

必修的：

Python>=3.11

可选（用于完整功能）：

Ruby+Bundler——使Rails运行器能够进行实时自检

（例如，精确的关联遍历、运行时方法解析）

ripgrep(rg)--由基于搜索的工具（find_references等）使用

没有Ruby： rails镜头支持基于文件的分析回退。大多数工具都有用通过直接解析Ruby文件得到结果。结果包括 _metadata.source: "file_analysis" 以指示回退模式。与Rails运行器模式相比，一些工具返回的数据有限。

功能	使用Ruby	不使用Ruby
模型列表	实时ActiveRecord扫描	文件glob+正则表达式
架构信息	数据库自检	DB/Schema.rb解析
关联	运行时评估	正则表达式提取
方法解析	完整祖先链	包含/扩展/前置推理
Gem自检	运行时方法注入	仅Gemfile/Gemfile.lock解析

安装

pip install rails-lens

工具

第1-4阶段：核心反思

______________________________________________________________________

`rails_lens_introspect_model`

内省单个Rails模型并返回其回调、关联、验证、作用域和类方法。

使用案例： 在修改模型之前，了解模型的完整行为。

参数：

model_name （string，必填）：Rails模型类名（例如。 "User", "Order")
include_inherited （boolean，可选）：包括继承的回调。违约： true

输出示例：

Model: User
Callbacks:
  before_save: :downcase_email, :strip_whitespace
  after_create: :send_welcome_email
Associations:
  has_many: :orders, :posts
  belongs_to: :organization
Validations:
  validates :email, presence: true, uniqueness: true

______________________________________________________________________

`rails_lens_list_models`

列出Rails应用程序中发现的所有ActiveRecord模型类。

使用案例： 在探索特定模型之前，先对数据模型进行概述。

参数： 无

输出示例：

Models (12):
  User, Order, Product, Category, Tag, Comment,
  Organization, Role, Permission, Session, AuditLog, Setting

______________________________________________________________________

`rails_lens_find_references`

使用快速文本搜索在代码库中搜索对给定方法或类名的所有引用。

使用案例： 在重命名或删除方法之前，在所有被调用的地方查找它。

参数：

name （string，必填）：要搜索的方法或类名
file_pattern （字符串，可选）：用于限制搜索的Glob模式（例如。 "app/**/*.rb")

输出示例：

References to "send_welcome_email" (3 found):
  app/models/user.rb:42    after_create :send_welcome_email
  app/mailers/user_mailer.rb:8    def send_welcome_email(user)
  spec/models/user_spec.rb:15    expect(user).to receive(:send_welcome_email)

______________________________________________________________________

`rails_lens_trace_callback_chain`

跟踪模型事件的完整回调链，包括来自关注点和父类的钩子。

使用案例： 在修改模型事件之前调试回调触发的意外行为。

参数：

model_name （string，必填）：Rails模型类名
event （string，必填）：回调事件（例如。 "before_save", "after_create")

示例输出（美人鱼图）：

graph TD
  A[before_save] --> B[:downcase_email]
  A --> C[:strip_whitespace]
  B --> D[defined in Concerns::Normalizable]
  C --> E[defined in User]

______________________________________________________________________

`rails_lens_dependency_graph`

生成显示模型之间关联的依赖关系图。

使用案例： 在重构或数据迁移之前，了解跨模型依赖关系。

参数：

root_model （字符串，可选）：图形的起始模型。如果省略，则绘制所有模型。
depth （整数，可选）：最大遍历深度。违约： 2

示例输出（美人鱼图）：

graph TD
  User -->|has_many| Order
  User -->|has_many| Post
  Order -->|belongs_to| User
  Order -->|has_many| LineItem
  LineItem -->|belongs_to| Product

______________________________________________________________________

`rails_lens_get_schema`

转储当前数据库架构（从 db/schema.rb)以结构化格式。

使用案例： 在编写迁移之前，请检查列类型和约束。

参数：

table_name （字符串，可选）：筛选到特定表。如果省略，则返回所有表。

输出示例：

Table: users
  id: bigint, primary key
  email: string, not null, unique
  created_at: datetime, not null
  updated_at: datetime, not null

______________________________________________________________________

`rails_lens_get_routes`

返回从以下位置定义的所有Rails路由 config/routes.rb 或 rails routes 输出。

使用案例： 验证可用路由及其控制器映射。

参数：

filter （字符串，可选）：按路径或控制器名称筛选路由

输出示例：

GET    /users          users#index
POST   /users          users#create
GET    /users/:id      users#show
PATCH  /users/:id      users#update
DELETE /users/:id      users#destroy

______________________________________________________________________

`rails_lens_analyze_concern`

分析Rails关注点模块，并列出它注入的方法、回调和验证。

使用案例： 在包含或删除问题之前，了解问题会给模型增加什么。

参数：

concern_name （字符串，必填）：关注模块名称（例如。 "Normalizable", "Auditable")

输出示例：

Concern: Concerns::Auditable
Injects callbacks:
  before_create: :set_creator
  before_update: :set_updater
Injects methods:
  :created_by_name, :updated_by_name
Injects validations:
  validates :creator, presence: true

______________________________________________________________________

`rails_lens_refresh_cache`

通过重新运行Rails脚本清除并重建自省缓存。

使用案例： 添加新模型或修改现有模型后刷新过时缓存。

参数：

model_name （字符串，可选）：仅刷新特定型号的缓存。如果省略，则全部刷新。

输出示例：

Cache refreshed for: User, Order, Product (3 models)
Duration: 4.2s

______________________________________________________________________

第五阶段：方法解析与宝石反思

______________________________________________________________________

`rails_lens_explain_method_resolution`

返回Rails模型的方法解析顺序（MRO）、祖先链和方法所有者。

使用案例： 当包含多个模块和关注点时，了解方法的定义位置。

参数：

model_name （string，必填）：Rails模型类名
method_name （string，可选）：定位的具体方法。如果省略，则返回完整的祖先链。
show_internal （boolean，可选）：包括Ruby/Rails内部模块。违约： false

输出示例：

{
  "model_name": "User",
  "method_owner": "Concerns::Normalizable",
  "ancestors": ["User", "Concerns::Auditable", "Concerns::Normalizable", "ApplicationRecord"],
  "super_chain": ["Concerns::Normalizable#downcase_email"],
  "monkey_patches": []
}

______________________________________________________________________

`rails_lens_gem_introspect`

返回Gems注入Rails模型的方法、回调和路由。

使用案例： 探索Devise、Paranoia、PaperTrail或其他宝石为模型添加了什么。

参数：

model_name （string，必填）：Rails模型类名
gem_name （string，可选）：将结果筛选到特定的gem。如果省略，则返回所有宝石。

输出示例：

{
  "model_name": "User",
  "gem_methods": [
    {"gem_name": "devise", "method_name": "authenticate", "source_file": null}
  ],
  "gem_callbacks": [
    {"gem_name": "paper_trail", "kind": "after_update", "event": "after_update", "method_name": "record_update"}
  ],
  "gem_routes": []
}

______________________________________________________________________

第6阶段：变更安全

______________________________________________________________________

`rails_lens_analyze_impact`

分析修改或删除列或方法的影响，包括回调、验证、视图、邮件程序和级联效应。

使用案例： 在重命名列或更改方法签名之前评估风险。

参数：

model_name （string，必填）：Rails模型类名
target （string，必填）：要分析的列或方法名称
change_type （字符串，可选）： remove, rename, type_change，或 modify默认值： modify

示例输出（美人鱼图）：

graph LR
  TARGET["User.email"]
  I0["VL: validates :email, presence: true"]
  I1["CB: before_save :downcase_email"]
  I2["VW: app/views/users/show.html.erb"]
  style I0 fill:#fa4
  style I1 fill:#fa4
  style I2 fill:#8f8
  TARGET --> I0
  TARGET --> I1
  TARGET --> I2

______________________________________________________________________

`rails_lens_test_mapping`

检测与模型或方法相关的测试文件，并返回run命令。

使用案例： 查找修改模型或方法后要运行的规范。

参数：

target （字符串，必填）：型号名称（例如。 "User")或方法规范（例如。 "User#activate")
include_indirect （布尔值，可选）：包括间接相关的规范（共享示例、功能规范）。违约： true

输出示例：

{
  "target": "User#activate",
  "test_framework": "rspec",
  "direct_tests": [
    {"file": "spec/models/user_spec.rb", "type": "unit", "relevance": "direct"}
  ],
  "indirect_tests": [
    {"file": "spec/features/user_registration_spec.rb", "type": "feature", "relevance": "indirect"}
  ],
  "run_command": "bundle exec rspec spec/models/user_spec.rb spec/features/user_registration_spec.rb"
}

______________________________________________________________________

第7阶段：重构

______________________________________________________________________

`rails_lens_dead_code`

使用置信度评级检测未使用的方法、回调和作用域。

使用案例： 在清理或重构会话期间找到安全的候选删除项。

参数：

scope （字符串，可选）：检测范围： models, controllers，或 all默认值： models
model_name （字符串，可选）：将检测限制在特定型号。
confidence （字符串，可选）： high （当然未使用）或 medium （可能是动态的）。违约： high

输出示例：

{
  "scope": "models",
  "total_methods_analyzed": 42,
  "total_dead_code_found": 3,
  "items": [
    {
      "type": "method", "name": "legacy_export", "file": "app/models/user.rb",
      "line": 87, "confidence": "high", "reason": "No references found",
      "reference_count": 0, "dynamic_call_risk": false
    }
  ]
}

______________________________________________________________________

`rails_lens_circular_dependencies`

检测模型之间的循环依赖关系（相互回调更新、双向关联），并将其可视化为Mermaid图。

使用案例： 识别相互触发对方回调、导致堆栈溢出或数据损坏的模型。

参数：

entry_point （字符串，可选）：筛选包含此模型的周期。
format （字符串，可选）： mermaid 或 json默认值： mermaid

示例输出（美人鱼图）：

graph LR
  Order["Order"]
  Invoice["Invoice"]
  Order -->|"after_save → update_invoice"| Invoice
  Invoice -->|"after_save → update_order"| Order
  style Order fill:#f88
  style Invoice fill:#f88

______________________________________________________________________

`rails_lens_extract_concern_candidate`

通过衔接分析胖模型的方法，并提出具有理论基础的关注点提取候选者。

使用案例： 识别大型模型中应提取为关注点的相关方法组。

参数：

model_name （string，必填）：Rails模型类名
min_cluster_size （整数，可选）：每个集群的最小方法数。违约： 3

输出示例：

{
  "model_name": "User",
  "total_methods": 45,
  "candidates": [
    {
      "suggested_name": "Notifiable",
      "methods": ["send_welcome_email", "send_reset_password", "notify_admin"],
      "cohesion_score": 0.87,
      "rationale": "All methods relate to email/notification dispatch"
    }
  ]
}

______________________________________________________________________

第8阶段：数据流和迁移

______________________________________________________________________

`rails_lens_data_flow`

跟踪从HTTP请求到路由、强参数、回调和数据库的数据流。

使用案例： 在修改用户提交的属性之前，了解其完整的生命周期。

参数：

controller_action （字符串，可选）：控制器#动作（例如。 "UsersController#create")
model_name （字符串，可选）：模型名称作为备选入口点
attribute （字符串，可选）：要跟踪的特定属性。如果省略，则全部跟踪。

示例输出（Mermaid序列图）：

sequenceDiagram
    participant Client
    participant Router
    participant Controller as UsersController
    participant Params as StrongParameters
    participant Model
    participant DB
    Client->>Router: POST /users
    Router->>Controller: #create
    Controller->>Params: permit(:name, :email, :password)
    Params->>Model: User.new(params)
    Model->>Model: before_save :downcase_email
    Model->>DB: INSERT INTO users

______________________________________________________________________

`rails_lens_migration_context`

为表提供迁移上下文：当前架构、迁移历史、安全警告和迁移模板。

使用案例： 在为大型表编写迁移之前，请获取所有相关的上下文和安全检查。

参数：

table_name （字符串，必填）：表名（例如。 "users")
operation （字符串，可选）：计划操作： add_column, remove_column, add_index, change_column, add_reference，或 general默认值： general

输出示例：

{
  "table_name": "users",
  "operation": "add_column",
  "estimated_row_count": 2500000,
  "warnings": [
    {
      "type": "large_table",
      "message": "Table has ~2.5M rows. Adding a non-null column without a default will lock the table.",
      "suggestion": "Use `add_column` with a default, then backfill and add NOT NULL constraint separately."
    }
  ],
  "template": {
    "description": "Add column with default for large table",
    "code": "add_column :users, :new_column, :string, default: nil\n# backfill...\nchange_column_null :users, :new_column, false"
  }
}

______________________________________________________________________

第9-10阶段：屏幕映射

______________________________________________________________________

`rails_lens_screen_map`

双向映射屏幕（URL/控制器操作）和源文件，并生成全屏清单。支持三种模式。

模式： `screen_to_source`

给定一个URL或控制器#操作，返回所有相关的源文件，包括模板、部分、助手、模型、装饰器、资产和i18n键。

使用案例： 在修改特定屏幕之前，了解渲染该屏幕所涉及的所有文件。

参数：

mode （字符串，必填）： "screen_to_source"
url （字符串，可选）：URL路径（例如。 "/users/123")
controller_action （字符串，可选）：控制器#动作（例如。 "UsersController#show")
locale （字符串，可选）：用于推断屏幕名称的语言。违约： "ja"

输出示例：

{
  "screen": {
    "url_pattern": "/users/:id",
    "http_method": "GET",
    "controller_action": "UsersController#show",
    "screen_name": "User Detail",
    "screen_name_source": "restful_convention"
  },
  "layout": {
    "file": "app/views/layouts/application.html.erb",
    "content_for_blocks": ["sidebar", "header"]
  },
  "template": {
    "file": "app/views/users/show.html.erb"
  },
  "partials": [
    {
      "name": "users/header",
      "file": "app/views/users/_header.html.erb",
      "called_from": "app/views/users/show.html.erb",
      "locals_passed": ["user"]
    }
  ],
  "helpers": [
    {"method": "format_date", "file": "app/helpers/application_helper.rb", "line": 12}
  ],
  "models": [
    {"model": "User", "attributes_accessed": ["name", "email"]}
  ]
}

______________________________________________________________________

模式： `source_to_screens`

给定一个源文件路径，返回使用它的所有屏幕以及更改的影响级别。

使用案例： 在修改部分或辅助程序之前，请了解哪些屏幕会受到影响。

参数：

mode （字符串，必填）： "source_to_screens"
file_path （string，必填）：源文件的路径（例如。 "app/views/shared/_navigation.html.erb")
method_name （字符串，可选）：用于缩小分析范围的辅助方法名称

输出示例：

{
  "source_file": "app/views/shared/_navigation.html.erb",
  "source_type": "partial",
  "affected_screens": [
    {
      "controller_action": "UsersController#index",
      "screen_name": "User List",
      "url_pattern": "/users",
      "impact_level": "high"
    },
    {
      "controller_action": "OrdersController#show",
      "screen_name": "Order Detail",
      "url_pattern": "/orders/:id",
      "impact_level": "high"
    }
  ]
}

______________________________________________________________________

模式： `full_inventory`

自动生成一个完整的屏幕清单，涵盖所有web屏幕和API端点。

使用案例： 为项目创建屏幕清单文档，或一目了然地查看所有屏幕。

参数：

mode （字符串，必填）： "full_inventory"
format （字符串，可选）：输出格式： "json" 或 "markdown"默认值： "json"
include_api （布尔型，可选）：包括API端点。违约： true
group_by （字符串，可选）：分组： "namespace", "resource"，或 "flat"默认值： "namespace"
locale （字符串，可选）：用于推断屏幕名称的语言。违约： "ja"

示例输出（markdown）：

# Screen Inventory

> Auto-generated by rails-lens

## Summary
- Total screens: 24
- Web screens: 18
- API endpoints: 6

## Web Screens

| Screen Name | URL | Controller#Action | Partials | Models |
|-------------|-----|-------------------|----------|--------|
| User List   | GET /users | UsersController#index | 3 | User |
| User Detail | GET /users/:id | UsersController#show | 5 | User |

______________________________________________________________________

Web仪表板

rails lens包括一个内置的web仪表板，用于在浏览器中可视化您的rails项目结构。

安装

pip install rails-lens[web]

用法

uvicorn rails_lens.web.app:app --host 0.0.0.0 --port 8000

或者使用Python模块：

python -m rails_lens.web

页面

核心（6页）

页面	URL	描述
仪表板顶部	`/`	项目概述、型号计数、缓存状态
型号列表	`/models`	所有具有列/关联计数的模型
型号详细信息	`/models/{name}`	模式、回调、Mermaid回调链
ER图	`/er`	实体关系图（Mermaid erDiagram）
依赖关系图	`/graph/{name}`	模型依赖图（Mermaid图LR）
缓存管理	`/cache`	缓存状态、无效控制

扩展（5页）

页面	URL	描述
项目健康	`/health`	循环依赖+死代码概述
请求流	`/flow`	HTTP请求→ DB流（美人鱼序列图）
影响分析	`/impact/{name}`	更改影响可视化
重构支持	`/refactor/{name}`	关注点提取候选者
宝石信息	`/gems`	已安装的gem及其Rails集成

技术栈

FastAPI+Jinja2+ PicoCSS + Mermaid.js

所有图表都是通过Mermaid.js在浏览器中呈现的，不需要生成服务器端的图像。

配置

`RAILS_LENS_PROJECT_PATH`

要分析的Rails应用程序根目录的绝对路径（包含 Gemfile, app/, config/, db/等等）。

这可以通过以下方式配置（按优先级顺序列出）：

环境变量 RAILS_LENS_PROJECT_PATH --作为MCP服务器（Claude Code/Cursor）运行时需要，因为服务器进程不是从Rails项目目录运行的。
rails.project_path 在 .rails-lens.toml --配置文件中的显式路径设置。
.rails-lens.toml 位置 --如果 .rails-lens.toml 如果放置在Rails项目根目录中，项目路径将从文件的父目录自动推断出来。没有明确 project_path 需要设置。

克劳德代码(`~/.claude/claude_desktop_config.json`)

{
  "mcpServers": {
    "rails-lens": {
      "command": "rails-lens",
      "env": {
        "RAILS_LENS_PROJECT_PATH": "/path/to/your/rails/project"
      }
    }
  }
}

光标(`.cursor/mcp.json`)

{
  "mcpServers": {
    "rails-lens": {
      "command": "rails-lens",
      "env": {
        "RAILS_LENS_PROJECT_PATH": "/path/to/your/rails/project"
      }
    }
  }
}

`.rails-lens.toml` （可选，在Rails项目根目录中）

当放置在Rails项目根目录中时， project_path 可以省略——它会自动从文件的位置解析出来。

[rails]
# project_path is inferred from this file's location
timeout = 30

[cache]
auto_invalidate = true

[search]
command = "rg"

开发人员设置

git clone https://github.com/ei-nakamura/rails-lens.git
cd rails-lens
pip install -e ".[dev]"
pytest tests/

跑步覆盖：

pytest tests/ --cov=src/rails_lens --cov-report=term-missing

看贡献.md 关于贡献指南。

许可证

麻省理工学院

Rails Lens

快速接入

详细介绍

轨道透镜

概述

需求

安装

工具

第1-4阶段：核心反思

rails_lens_introspect_model

rails_lens_list_models

rails_lens_find_references

rails_lens_trace_callback_chain

rails_lens_dependency_graph

rails_lens_get_schema

rails_lens_get_routes

rails_lens_analyze_concern

rails_lens_refresh_cache

第五阶段：方法解析与宝石反思

rails_lens_explain_method_resolution

rails_lens_gem_introspect

第6阶段：变更安全

rails_lens_analyze_impact

rails_lens_test_mapping

第7阶段：重构

rails_lens_dead_code

rails_lens_circular_dependencies

rails_lens_extract_concern_candidate

第8阶段：数据流和迁移

rails_lens_data_flow

rails_lens_migration_context

第9-10阶段：屏幕映射

rails_lens_screen_map

模式： screen_to_source

模式： source_to_screens

模式： full_inventory

Web仪表板

安装

用法

页面

技术栈

配置

RAILS_LENS_PROJECT_PATH

克劳德代码(~/.claude/claude_desktop_config.json)

光标(.cursor/mcp.json)

.rails-lens.toml （可选，在Rails项目根目录中）

开发人员设置

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`rails_lens_introspect_model`

`rails_lens_list_models`

`rails_lens_find_references`

`rails_lens_trace_callback_chain`

`rails_lens_dependency_graph`

`rails_lens_get_schema`

`rails_lens_get_routes`

`rails_lens_analyze_concern`

`rails_lens_refresh_cache`

`rails_lens_explain_method_resolution`

`rails_lens_gem_introspect`

`rails_lens_analyze_impact`

`rails_lens_test_mapping`

`rails_lens_dead_code`

`rails_lens_circular_dependencies`

`rails_lens_extract_concern_candidate`

`rails_lens_data_flow`

`rails_lens_migration_context`

`rails_lens_screen_map`

模式： `screen_to_source`

模式： `source_to_screens`

模式： `full_inventory`

`RAILS_LENS_PROJECT_PATH`

克劳德代码(`~/.claude/claude_desktop_config.json`)

光标(`.cursor/mcp.json`)

`.rails-lens.toml` （可选，在Rails项目根目录中）