rails_mcp_code_search
Semantic codebase search for Claude Code via MCP
Think Cursor's codebase indexing, but for Claude Code.
How It Works ◆ Quick Start ◆ Tools ◆ Configuration ◆ Architecture
______________________________________________________________________
运作原理
- Ruby文件 --解析为 棱镜 分为类、模块和方法
- ERB模板 --解析为 草药 分为块、条件句和HTML元素
- 其他文件 （JS、TS、YAML、Markdown）——滑动窗口分块
- 嵌入 --本地生成 全迷你LM-L6-v2 （384个维度，零配置）
- 向量搜索 --SQLite+ sqlite-vc 余弦相似性
- 后台索引 --自动启动，搜索立即可用
快速开始
gem install rails_mcp_code_search
cd your-project
rails-mcp-code-search --setup需要Ruby 4.0+。跑 --setup 在您要索引的每个项目中。它创建了一个与版本无关的包装器脚本(~/.local/bin/)每个项目一个 .mcp.json 自动配置Claude Code。gem自动每天更新。第一次搜索将嵌入模型（约80 MB）下载到 ~/.cache/informers/.
提示： 添加.mcp.json到你的项目.gitignore--它包含本地路径。
工具
搜索
使用自然语言按概念或行为搜索代码库。
query: "user authentication logic"
limit: 10
file_pattern: "app/models/**/*.rb"返回排名结果，包括文件路径、行范围、相似性得分和代码内容。每次搜索时，更改的文件都会自动重新索引，时间预算为200毫秒。
重新索引
触发手动重新索引。立即返回--在后台运行。
full: true # Rebuild entire index
full: false # Incremental (default, only changed files)状态
检查索引运行状况、块计数、嵌入提供程序和搜索统计信息。
配置
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
RAILS_MCP_CODE_SEARCH_PROVIDER | local | 嵌入提供程序： local 或 openai |
RAILS_MCP_CODE_SEARCH_DB_PATH | auto | 覆盖数据库文件路径 |
RAILS_MCP_CODE_SEARCH_LOG_LEVEL | info | 日志级别： debug, info, warn, error |
RAILS_MCP_CODE_SEARCH_OPENAI_API_KEY | -- | 提供程序为时必需 openai |
OpenAI提供商
为了实现更快的索引或更高维的嵌入，请使用OpenAI text-embedding-3-small （1536个维度）：
export RAILS_MCP_CODE_SEARCH_PROVIDER=openai
export RAILS_MCP_CODE_SEARCH_OPENAI_API_KEY=sk-...| 本地（默认） | OpenAI | |
|---|---|---|
| 尺寸 | 384 | 1536 |
| 速度 | ~5分钟/1000个文件 | ~15s/1000个文件 |
| 成本 | 免费 | API成本 |
| 隐私 | 一切都是本地的 | 代码发送到OpenAI |
| 设置 | 零配置 | 需要API密钥 |
切换提供者会自动触发完整的重新索引。
隐私声明： 使用OpenAI提供程序时，存储库中的源代码块将发送到OpenAI的嵌入API。本地提供者（默认）将所有内容保存在您的计算机上。
支持的文件类型
*.rb *.erb *.js *.ts *.yml *.yaml *.md
排除： vendor/ node_modules/ tmp/ log/
建筑
┌─────────────────────────────────────────────────────────┐
│ Claude Code │
│ (MCP Client) │
└──────────────────────┬──────────────────────────────────┘
│ stdio
▼
┌─────────────────────────────────────────────────────────┐
│ MCP Server (search, reindex, status) │
└──────────────────────┬──────────────────────────────────┘
│
┌────────────┴────────────┐
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Background │ │ Embedding │
│ Worker │ │ Adapter │
│ (sole writer) │ │ (local / openai) │
└────────┬─────────┘ └────────┬─────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────┐
│ SQLite + sqlite-vec │
│ (WAL mode, per-project DB) │
│ ~/.local/share/rails-mcp-code-search/ │
└─────────────────────────────────────────────┘解析器
| 文件类型 | 解析器 | 块类型 |
|---|---|---|
*.rb | 棱镜AST | class, module, method |
*.erb | 草本AST | erb_block, erb_conditional, html_element |
| 其他一切 | 滑动窗 | window （50行，10行重叠） |
关键设计决策
- 独立ActiveRecord --没有Rails运行时依赖，只有SQLite
- 单作者线程 --所有DB突变都通过后台工作者
- 智能重新索引 --更改文件（通过
git diff)在每次搜索之前重新索引 - 每个项目数据库 --项目路径的SHA256，存储在
~/.local/share/ - 棱镜+草本AST --语义组块比简单的行分割产生更好的搜索结果
许可证
麻省理工学院
______________________________________________________________________
Made in Tokyo with ❤️ and 🤖