ganjooh/rails-ast-mcp-server

Rails AST MCP Server

An intelligent MCP (Model Context Protocol) server for Ruby on Rails projects that provides AST-based code parsing, knowledge graph navigation, and advanced analysis capabilities. Features native Ruby AST parsing with automatic fallback to regex-based parsing when Ruby is not available.

Why Use Rails AST MCP Server?

Advantages Over Vanilla Claude Code / Cursor

Key Benefits

1. Context Efficiency: Instead of loading entire files into Claude's context window, you can query specific symbols and relationships
2. Rails Intelligence: Understands Rails DSL - knows that has_many :posts creates methods like posts, posts=, posts<<, etc.
3. Speed: Pre-indexed database means instant searches vs scanning files every time
4. Accurate Symbol Detection: Native Ruby AST parsing (when available) ensures 100% accurate symbol detection

Features

• 🔍 Smart Symbol Search: Find classes, methods, modules across your Rails codebase
• 📊 Call Graph Analysis: Trace method calls and dependencies
• 🧪 Test Discovery: Automatically find related test files
• 📁 Rails-aware: Understands Rails conventions and patterns
• 🚀 Hybrid Parsing: Native Ruby AST when available, regex fallback otherwise
• ⚡ Fast Search: SQLite FTS5 full-text search for instant results
• 🎯 Context Efficient: Minimizes token usage by returning only relevant code
• 🗄️ Schema Awareness: Parses db/schema.rb to understand database structure
• 🔗 Association Suggestions: Automatically suggests Rails associations from foreign keys
• ✅ Validation Generation: Suggests validations based on database constraints

Quick Start

Claude Code

# Add the server for your Rails project (requires full path)
claude mcp add rails-ast npx -- -y rails-ast-mcp-server /path/to/your/rails/project

# Example:
claude mcp add rails-ast npx -- -y rails-ast-mcp-server /Users/you/sources/my-rails-app

# Restart Claude Code to activate the server

Important: Always use the full absolute path to your Rails project

Configuration

Command Line Arguments

The server accepts a single argument for the repository path:

# Specify the Rails project path as an argument
npx rails-ast-mcp-server /path/to/rails/project

# Or use current directory
npx rails-ast-mcp-server .

Environment Variables

You can also configure the server using environment variables:

# Example with environment variables
REPO_PATH=/path/to/rails/app DB_PATH=/tmp/index.db npx rails-ast-mcp-server

# Disable auto-indexing
AUTO_INDEX=false npx @hiteshganjoo/rails-mcp-indexer

Auto-Indexing Features (v2.1.0+)

The indexer now includes intelligent auto-indexing capabilities:

1. Automatic Index on Startup

• Automatically indexes your Rails project when the server starts
• Only indexes if:
  • Database doesn't exist (first run)
  • Repository path has changed
  • Database is empty
• Skips indexing if the existing index is valid
• Can be disabled with AUTO_INDEX=false

2. Project-Specific Database

• Database is now stored at {project}/.rails-index/repo.db by default
• Each Rails project gets its own index
• No more conflicts when switching between projects

3. Incremental Indexing

• Only re-indexes files that have changed since last index
• Checks file modification times vs last index time
• Much faster than full reindex for large projects

4. Smart Reindexing Detection

• Automatically detects when a full reindex is needed:
  • When switching to a different Rails project
  • When the database is corrupted or missing
  • When explicitly requested via the reindex tool

Project-Specific Configuration

Create a .mcp.json file in your Rails project root:

{
  "rails-indexer": {
    "repoPath": ".",
    "dbPath": ".rails-index/repo.db",
    "autoIndex": true
  }
}

Available Tools

🔍 search_symbols

Search for symbols (classes, methods, modules) in your codebase.

{
  "query": "User",           // Search query
  "k": 10,                   // Number of results (default: 10)
  "file_types": ["model"]    // Optional: Filter by file types
}

📝 get_snippet

Extract code snippets from files.

{
  "file_path": "app/models/user.rb",
  "start_line": 10,          // Optional
  "end_line": 20,            // Optional
  "symbol_name": "validate"  // Optional: Extract specific symbol
}

📊 call_graph

Analyze call relationships between methods.

{
  "symbol": "User.authenticate",
  "direction": "both",       // "callers" | "callees" | "both"
  "depth": 2                 // Analysis depth
}

🔄 find_similar

Find code patterns similar to a given snippet.

{
  "code_snippet": "validates :email, presence: true",
  "k": 5,                   // Number of results
  "min_similarity": 0.7     // Minimum similarity score
}

🧪 find_tests

Find test files related to an implementation file.

{
  "file_path": "app/models/user.rb"
}

🔄 reindex

Reindex the codebase.

{
  "paths": ["app/models"],  // Optional: Specific paths
  "full": false             // Full reindex
}

🗄️ db_tables

List all database tables from schema.rb.

// No parameters required

📊 db_table

Get detailed information about a database table including columns, indexes, and constraints.

{
  "table_name": "users"
}

🔗 db_table_relations

Get foreign key relationships for a table.

{
  "table_name": "orders"
}

💡 db_suggest_associations

Suggest Rails associations and validations based on database schema.

{
  "table_name": "posts"
}

Returns:

• Rails association declarations (belongs_to, has_many, has_one)
• Validation suggestions based on constraints
• Model name inference

Database Schema Support

The indexer automatically parses db/schema.rb to provide database-aware features:

Automatic Schema Indexing

• Parses db/schema.rb during reindex
• Extracts tables, columns, indexes, and foreign keys
• Stores schema metadata in SQLite for fast queries

Rails Association Generation

Based on foreign keys in your schema, the indexer suggests:

• belongs_to associations for foreign key columns
• has_many or has_one based on unique constraints
• Proper dependent options from ON DELETE rules
• inverse_of relationships

Validation Suggestions

Automatically suggests validations based on:

• NOT NULL constraints → presence: true
• Unique indexes → uniqueness: true
• String column limits → length: { maximum: X }
• Numeric columns → numericality validations

Rails File Type Recognition

The indexer automatically recognizes these Rails patterns:

How It Works

1. Parsing: Hybrid approach - native Ruby AST parser when Ruby is available, regex fallback otherwise
2. Indexing: Stores parsed data in SQLite with FTS5 for fast search
3. MCP Protocol: Exposes tools via Model Context Protocol for AI assistants

Ruby Support (Optional)

The indexer works without Ruby installation, but having Ruby installed provides more accurate parsing:

When Ruby is detected during installation, the package automatically:

1. Detects your Ruby version
2. Installs appropriate parser gems
3. Uses native AST parsing for 100% accurate symbol detection
4. Falls back to regex parsing if native parsing fails

Architecture

┌──────────────────┐     ┌──────────────────┐
│  Claude/AI Agent │────▶│   MCP Protocol   │
└──────────────────┘     └──────────────────┘
                                │
                                ▼
                         ┌──────────────────┐
                         │  Rails MCP Server│
                         └──────────────────┘
                                │
                ┌───────────────┼───────────────┐
                ▼               ▼               ▼
         ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
         │ Ruby Parser  │ │   Indexer    │ │   Database   │
         └──────────────┘ └──────────────┘ └──────────────┘
                │               │               │
                └───────────────┼───────────────┘
                                ▼
                        ┌──────────────────┐
                        │  Rails Codebase  │
                        └──────────────────┘

Development

Prerequisites

• Node.js 18+
• TypeScript 5+

Setup

# Clone the repository
git clone https://github.com/ganjooh/rails-ast-mcp-server
cd rails-ast-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Test with sample Rails app
REPO_PATH=./sample_rails_app npm start

Testing

# Run tests
npm test

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npm start

Usage Examples

Real-World Advantages in Claude Code

Without Rails MCP Indexer (Vanilla Claude Code)

User: "Find all authentication methods in my Rails app"
Claude: *Searches through multiple files, uses significant context*
"Let me search through your codebase... 
Reading app/models/user.rb...
Reading app/controllers/application_controller.rb...
Reading app/controllers/sessions_controller.rb..."
[Uses 5000+ tokens just to find methods]

With Rails MCP Indexer

User: "Find all authentication methods in my Rails app"
Claude: *Instantly queries the index*
Found 5 authentication-related methods:
- User.authenticate (app/models/user.rb:37)
- SessionsController#create (app/controllers/sessions_controller.rb:8)
- ApplicationController#authenticate_user! (app/controllers/application_controller.rb:15)
[Uses only 200 tokens with precise results]

Common Use Cases

1. Finding Symbol Definitions

# Ask Claude Code:
"Where is the User.authenticate method defined?"
# Rails MCP Indexer instantly returns: app/models/user.rb:37-41

# Vanilla Claude Code would need to:
# - Search through all model files
# - Parse each file to find the method
# - Use significant context tokens

2. Understanding Model Relationships

# Ask Claude Code:
"What associations does the User model have?"
# Rails MCP Indexer knows:
# - has_many :posts
# - has_many :comments, through: :posts
# - has_one :profile
# - belongs_to :organization

# Vanilla Claude Code would need to load and parse the entire User model

3. Finding Related Tests

# Ask Claude Code:
"Find tests for the User model"
# Rails MCP Indexer instantly returns:
# - spec/models/user_spec.rb
# - spec/requests/users_spec.rb
# - test/models/user_test.rb

# Vanilla Claude Code would manually search through spec/ and test/ directories

Direct Tool Usage

// Example: Search for authentication-related symbols
const result = await mcpClient.callTool('search_symbols', {
  query: 'authenticate',
  k: 5,
  file_types: ['model', 'controller']
});

// Example: Get call graph for a method
const graph = await mcpClient.callTool('call_graph', {
  symbol: 'User.authenticate',
  direction: 'both',
  depth: 2
});

// Example: Find similar validation patterns
const similar = await mcpClient.callTool('find_similar', {
  code_snippet: 'validates :email, presence: true, uniqueness: true',
  k: 5
});

Troubleshooting

Server not connecting

1. Check Node.js version: node --version (should be 18+)
2. Verify paths: Ensure REPO_PATH points to valid Rails project
3. Check logs: Run with DEBUG=* npm start

Index not updating

1. Run reindex: Use the reindex tool with full: true
2. Check permissions: Ensure write access to DB_PATH directory
3. Verify file patterns: Check if your Rails structure matches expected patterns

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

Built with Model Context Protocol SDK for seamless AI integration.