rails-mcp-server 1.1.3 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +209 -0
  3. data/README.md +157 -47
  4. data/config/resources.yml +203 -0
  5. data/docs/RESOURCES.md +339 -0
  6. data/exe/rails-mcp-server +18 -7
  7. data/exe/rails-mcp-server-download-resources +120 -0
  8. data/lib/rails-mcp-server/config.rb +7 -1
  9. data/lib/rails-mcp-server/extensions/resource_templating.rb +182 -0
  10. data/lib/rails-mcp-server/extensions/server_templating.rb +333 -0
  11. data/lib/rails-mcp-server/helpers/resource_base.rb +143 -0
  12. data/lib/rails-mcp-server/helpers/resource_downloader.rb +104 -0
  13. data/lib/rails-mcp-server/helpers/resource_importer.rb +113 -0
  14. data/lib/rails-mcp-server/resources/base_resource.rb +7 -0
  15. data/lib/rails-mcp-server/resources/custom_guides_resource.rb +54 -0
  16. data/lib/rails-mcp-server/resources/custom_guides_resources.rb +37 -0
  17. data/lib/rails-mcp-server/resources/guide_content_formatter.rb +130 -0
  18. data/lib/rails-mcp-server/resources/guide_error_handler.rb +85 -0
  19. data/lib/rails-mcp-server/resources/guide_file_finder.rb +100 -0
  20. data/lib/rails-mcp-server/resources/guide_framework_contract.rb +65 -0
  21. data/lib/rails-mcp-server/resources/guide_loader_template.rb +122 -0
  22. data/lib/rails-mcp-server/resources/guide_manifest_operations.rb +52 -0
  23. data/lib/rails-mcp-server/resources/kamal_guides_resource.rb +80 -0
  24. data/lib/rails-mcp-server/resources/kamal_guides_resources.rb +110 -0
  25. data/lib/rails-mcp-server/resources/rails_guides_resource.rb +29 -0
  26. data/lib/rails-mcp-server/resources/rails_guides_resources.rb +37 -0
  27. data/lib/rails-mcp-server/resources/stimulus_guides_resource.rb +29 -0
  28. data/lib/rails-mcp-server/resources/stimulus_guides_resources.rb +37 -0
  29. data/lib/rails-mcp-server/resources/turbo_guides_resource.rb +29 -0
  30. data/lib/rails-mcp-server/resources/turbo_guides_resources.rb +37 -0
  31. data/lib/rails-mcp-server/tools/get_schema.rb +2 -2
  32. data/lib/rails-mcp-server/tools/load_guide.rb +370 -0
  33. data/lib/rails-mcp-server/utilities/run_process.rb +2 -0
  34. data/lib/rails-mcp-server/version.rb +1 -1
  35. data/lib/rails_mcp_server.rb +51 -283
  36. metadata +48 -5
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 02c77d8a0a509c668fbac9499082d11ab59e3acc3e8e06f9dcb932c37344efdb
4
- data.tar.gz: 50ee750a4af047013fa27db79a82007c59668593f9b5efbb67fa2e5024df37e8
3
+ metadata.gz: d223ba6b32da76211f1b0316c76156453acfc25f86a2b2750949b5747cf4c2b2
4
+ data.tar.gz: c3bfbaa694738d88186f761c6053edffed7324d3a68a9168c91b63757250ad49
5
5
  SHA512:
6
- metadata.gz: 83d380f54c9ad929e20a14f755d641687bced98349b6c7f1b8931077b55fab5a4f63992163ff017d836eb3ae67368573af88957c571fb13e1f8da2fdd9670451
7
- data.tar.gz: 0aba6aa7ba7c0bb3e6e8439b60326a64bcbee080d81d981771857d12323ae522483464d1daae0a87f38d8abd115516a21f28c4880205a08316ccec596d17453f
6
+ metadata.gz: '08cf5e172f3ad00d8e8fbcca061bd5c06fd3a6dfcac6610849f3cf9dda86a10a4bfa6c254804309e421bc64370382fe4a90e0456b82c3aa1aa14214d5f0a8be8'
7
+ data.tar.gz: 6c8a18e379e46f5c3a55554f244b48b1f01477dc1283911f198c0876cbeeaa6fccb8dccb6a972cdc2a7a218b42a8e07e9928a3a2d8a457eafad4b33f625e995d
data/CHANGELOG.md ADDED
@@ -0,0 +1,209 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [1.2.0] - 2025-06-03
9
+
10
+ ### Added
11
+
12
+ - **Comprehensive Resources and Documentation System**: Complete access to Rails ecosystem documentation
13
+ - `load_guide` tool for accessing official framework documentation
14
+ - Support for Rails, Turbo, Stimulus, and Kamal documentation
15
+ - Custom markdown file import capabilities
16
+ - Automatic resource downloading via `rails-mcp-server-download-resources` command
17
+ - Resource storage in XDG-compliant directories with manifest tracking
18
+ - **Five Resource Categories**:
19
+ - **Rails Guides**: Official Ruby on Rails 8.0.2 documentation (50+ guides)
20
+ - **Turbo Guides**: Complete Hotwire Turbo framework documentation
21
+ - **Stimulus Guides**: Full Stimulus JavaScript framework documentation
22
+ - **Kamal Guides**: Comprehensive Kamal deployment tool documentation
23
+ - **Custom Guides**: Import and manage your own markdown documentation
24
+ - **Direct Resource Access**: MCP clients can query resources using URI templates
25
+ - `rails://guides/{guide_name}` for Rails documentation
26
+ - `turbo://guides/{guide_name}` for Turbo guides
27
+ - `stimulus://guides/{guide_name}` for Stimulus documentation
28
+ - `kamal://guides/{guide_name}` for Kamal guides
29
+ - `custom://guides/{guide_name}` for custom imports
30
+ - **Advanced Resource Management**:
31
+ - Force download options (`--force`) for updating resources
32
+ - Verbose logging (`--verbose`) for troubleshooting
33
+ - Batch import support for directory structures
34
+ - Filename normalization for custom imports
35
+ - Version tracking and update management
36
+
37
+ ### Improved
38
+
39
+ - **Enhanced Documentation**: All tools now include comprehensive natural language examples
40
+ - **Resource Integration**: Seamless integration with existing MCP tool ecosystem
41
+ - **File Organization**: Better project structure with XDG Base Directory compliance
42
+ - **Error Handling**: Improved validation and error messages across resource operations
43
+
44
+ ### Technical
45
+
46
+ - URI templating support for direct resource access
47
+ - Enhanced manifest management for resource tracking
48
+ - Integration with FastMCP for robust resource handling
49
+ - Simplified guides configuration and management
50
+
51
+ ## [1.1.4] - 2025-05-02
52
+
53
+ ### Fixed
54
+
55
+ - **HTTP Mode Issues**: Resolved Puma server startup failures in HTTP mode
56
+ - **Rails Command Execution**: Fixed issues with executing Rails commands in certain environments
57
+ - **Logger Configuration**: Fixed logger initialization when no config file exists (thanks to @justwiebe)
58
+
59
+ ### Changed
60
+
61
+ - Improved dependency version constraints for better compatibility
62
+ - Enhanced error handling for HTTP server operations
63
+
64
+ ## [1.1.0] - 2025-04-20
65
+
66
+ ### Added
67
+
68
+ - **HTTP Server-Sent Events (SSE) Support**: Real-time communication capabilities
69
+ - HTTP mode with JSON-RPC and SSE endpoints (`--mode http`)
70
+ - Custom port configuration with `-p/--port` option
71
+ - SSE endpoint at `/mcp/sse` for real-time updates
72
+ - JSON-RPC endpoint at `/mcp/messages`
73
+ - **New Analysis Tools**:
74
+ - `analyze_controller_views`: Analyze relationships between controllers, actions, and views
75
+ - `analyze_environment_config`: Compare environment configurations for inconsistencies and security issues
76
+ - **Enhanced Integration**:
77
+ - MCP Inspector compatibility for testing and debugging
78
+ - Improved client compatibility through HTTP endpoints
79
+ - Better support for multiple LLM clients
80
+
81
+ ### Improved
82
+
83
+ - **Code Organization**: Major refactoring using FastMCP gem
84
+ - Transition from mcp-rb to fast-mcp for better protocol support
85
+ - Enhanced modular architecture for better maintainability
86
+ - Improved error handling and validation across all tools
87
+ - **File System Respect**: All tools now respect `.gitignore` files when scanning codebases
88
+ - **Tool Enhancements**: Comprehensive review and improvement of all existing tools
89
+ - Better edge case handling for large projects
90
+ - Performance improvements for file operations
91
+ - Enhanced logging and debugging capabilities
92
+
93
+ ### Technical
94
+
95
+ - **FastMCP Integration**: Complete migration to FastMCP gem for robust MCP protocol implementation
96
+ - **Rack-based Architecture**: HTTP server implementation using Rack
97
+ - **Event-driven Communication**: Real-time event handling for SSE support
98
+ - **Improved Connection Management**: Better handling of client connections and message processing
99
+
100
+ ### Changed
101
+
102
+ - **Internal Architecture**: Complete refactoring to use FastMCP instead of mcp-rb
103
+ - **Command-line Interface**: Enhanced CLI with mode selection and configuration options
104
+ - **Documentation**: Updated with detailed tool descriptions and usage examples
105
+
106
+ ## [1.0.0] - 2025-03-20
107
+
108
+ ### Added
109
+
110
+ - **Initial Release**: Rails MCP Server for AI-assisted Rails development
111
+ - **Core Tools** (8 tools):
112
+ - `switch_project`: Change active Rails project for multi-project support
113
+ - `project_info`: Get comprehensive Rails project information and structure
114
+ - `list_files`: Browse project files with glob pattern matching
115
+ - `get_file`: Retrieve file contents with syntax highlighting
116
+ - `get_routes`: Display all Rails routes (equivalent to `rails routes`)
117
+ - `analize_models`: Analyze Active Record models, associations, and relationships
118
+ - `get_schema`: Retrieve database schema information and table structures
119
+ - Basic file and project analysis capabilities
120
+ - **Project Management System**:
121
+ - Multi-project support through `projects.yml` configuration
122
+ - XDG Base Directory Specification compliance for configuration
123
+ - Automatic project detection and setup
124
+ - Cross-platform compatibility (macOS, Windows)
125
+ - **Claude Desktop Integration**:
126
+ - STDIO mode communication for direct integration
127
+ - Automatic setup script (`rails-mcp-setup-claude`)
128
+ - Ruby version manager compatibility documentation
129
+ - JSON-RPC 2.0 protocol implementation
130
+ - **Developer Experience**:
131
+ - Comprehensive logging system with configurable levels
132
+ - Debug mode and verbose output options
133
+ - Robust error handling and validation
134
+ - Clear documentation and setup guides
135
+
136
+ ### Features
137
+
138
+ - **Rails-Specific Intelligence**: Deep understanding of Rails application architecture
139
+ - Model relationships and Active Record associations analysis
140
+ - Controller and route mapping
141
+ - Database schema exploration and relationship discovery
142
+ - Rails convention-based file discovery
143
+ - **Smart File System Integration**:
144
+ - Intelligent file discovery with glob pattern support
145
+ - Automatic respect for Rails conventions and `.gitignore`
146
+ - Syntax highlighting for various file types
147
+ - Efficient handling of large codebases
148
+ - **Configuration Management**:
149
+ - Platform-specific configuration directories
150
+ - Project-based organization and switching
151
+ - Automatic initialization and setup
152
+ - Secure and isolated project environments
153
+
154
+ ### Technical Foundation
155
+
156
+ - **Model Context Protocol (MCP)**: Full MCP specification implementation
157
+ - **Communication**: JSON-RPC 2.0 protocol over STDIO
158
+ - **Architecture**: Modular, extensible design for future enhancements
159
+ - **Distribution**: Ruby gem packaging for easy installation and updates
160
+ - **Compatibility**: Cross-platform support with platform-specific optimizations
161
+
162
+ ---
163
+
164
+ ## Version History Summary
165
+
166
+ - **v1.2.0** (2025-06-03): Major documentation and resource system addition
167
+ - **v1.1.4** (2025-05-02): Critical bug fixes for HTTP mode and Rails commands
168
+ - **v1.1.0** (2025-04-20): HTTP SSE support and new analysis tools with FastMCP migration
169
+ - **v1.0.0** (2025-03-20): Initial release with core Rails MCP functionality
170
+
171
+ ## Development Guidelines
172
+
173
+ ### Version Numbering
174
+
175
+ This project follows [Semantic Versioning](https://semver.org/):
176
+
177
+ - **MAJOR** version for incompatible API changes
178
+ - **MINOR** version for backwards-compatible functionality additions
179
+ - **PATCH** version for backwards-compatible bug fixes
180
+
181
+ ### Release Process
182
+
183
+ 1. Update version in `lib/rails-mcp-server/version.rb`
184
+ 2. Update this CHANGELOG.md with new features and changes
185
+ 3. Update README.md and documentation if needed
186
+ 4. Create a git tag: `git tag -a v1.2.0 -m "Release version 1.2.0"`
187
+ 5. Push tags: `git push origin --tags`
188
+ 6. Build and publish gem: `gem build rails-mcp-server.gemspec && gem push rails-mcp-server-1.2.0.gem`
189
+
190
+ ### Changelog Categories
191
+
192
+ - **Added** for new features
193
+ - **Changed** for changes in existing functionality
194
+ - **Deprecated** for soon-to-be removed features
195
+ - **Removed** for now removed features
196
+ - **Fixed** for any bug fixes
197
+ - **Security** for vulnerability fixes
198
+ - **Technical** for internal/technical improvements
199
+ - **Improved** for enhancements to existing features
200
+
201
+ ---
202
+
203
+ ## Links
204
+
205
+ - [Repository](https://github.com/maquina-app/rails-mcp-server)
206
+ - [Releases](https://github.com/maquina-app/rails-mcp-server/releases)
207
+ - [Issues](https://github.com/maquina-app/rails-mcp-server/issues)
208
+ - [Documentation](https://github.com/maquina-app/rails-mcp-server#readme)
209
+ - [Resources Guide](docs/RESOURCES.md)
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Rails MCP Server
2
2
 
3
- A Ruby implementation of a Model Context Protocol (MCP) server for Rails projects. This server allows LLMs (Large Language Models) to interact with Rails projects through the Model Context Protocol.
3
+ A Ruby implementation of a Model Context Protocol (MCP) server for Rails projects. This server allows LLMs (Large Language Models) to interact with Rails projects through the Model Context Protocol, providing capabilities for code analysis, exploration, and development assistance.
4
4
 
5
5
  ## What is MCP?
6
6
 
@@ -13,11 +13,13 @@ This Rails MCP Server implements the MCP specification to give AI models access
13
13
  - Manage multiple Rails projects
14
14
  - Browse project files and structures
15
15
  - View Rails routes
16
- - Inspect model information
16
+ - Inspect model information and relationships
17
17
  - Get database schema information
18
18
  - Analyze controller-view relationships
19
19
  - Analyze environment configurations
20
+ - Access comprehensive Rails, Turbo, Stimulus, and Kamal documentation
20
21
  - Follow the Model Context Protocol standard
22
+ - Seamless integration with LLM clients
21
23
 
22
24
  ## Installation
23
25
 
@@ -45,10 +47,45 @@ To configure your projects:
45
47
  ```yaml
46
48
  store: "~/projects/store"
47
49
  blog: "~/projects/rails-blog"
50
+ ecommerce: "/full/path/to/ecommerce-app"
48
51
  ```
49
52
 
50
53
  Each key in the YAML file is a project name (which will be used with the `switch_project` tool), and each value is the path to the project directory.
51
54
 
55
+ ## Usage
56
+
57
+ ### Starting the server
58
+
59
+ The Rails MCP Server can run in two modes:
60
+
61
+ 1. **STDIO mode (default)**: Communicates over standard input/output for direct integration with clients like Claude Desktop.
62
+ 2. **HTTP mode**: Runs as an HTTP server with JSON-RPC and Server-Sent Events (SSE) endpoints.
63
+
64
+ ```bash
65
+ # Start in default STDIO mode
66
+ rails-mcp-server
67
+
68
+ # Start in HTTP mode on the default port (6029)
69
+ rails-mcp-server --mode http
70
+
71
+ # Start in HTTP mode on a custom port
72
+ rails-mcp-server --mode http -p 8080
73
+ ```
74
+
75
+ When running in HTTP mode, the server provides two endpoints:
76
+
77
+ - JSON-RPC endpoint: `http://localhost:<port>/mcp/messages`
78
+ - SSE endpoint: `http://localhost:<port>/mcp/sse`
79
+
80
+ ### Logging Options
81
+
82
+ The server logs to a file in the `./log` directory by default. You can customize logging with these options:
83
+
84
+ ```bash
85
+ # Set the log level (debug, info, error)
86
+ rails-mcp-server --log-level debug
87
+ ```
88
+
52
89
  ## Claude Desktop Integration
53
90
 
54
91
  The Rails MCP Server can be used with Claude Desktop. There are two options to set this up:
@@ -69,10 +106,10 @@ The script will:
69
106
 
70
107
  After running the script, restart Claude Desktop to apply the changes.
71
108
 
72
- ### Option 2: Manual configuration
109
+ ### Option 2: Direct Configuration
73
110
 
74
111
  1. Create the appropriate config directory for your platform:
75
- - macOS: `$XDG_CONFIG_HOME/rails-mcp` or `~/.config/rails-mcp`
112
+ - macOS: `$XDG_CONFIG_HOME/rails-mcp` or `~/.config/rails-mcp` if XDG_CONFIG_HOME is not set
76
113
  - Windows: `%APPDATA%\rails-mcp`
77
114
 
78
115
  2. Create a `projects.yml` file in that directory with your Rails projects.
@@ -102,48 +139,47 @@ Claude Desktop launches the MCP server using your system's default Ruby environm
102
139
 
103
140
  If you are using a Ruby version manager such as rbenv, you can create a symbolic link to your Ruby shim to ensure the correct version is used:
104
141
 
105
- ```
106
-
142
+ ```bash
107
143
  sudo ln -s /home/your_user/.rbenv/shims/ruby /usr/local/bin/ruby
108
-
109
144
  ```
110
145
 
111
146
  Replace "/home/your_user/.rbenv/shims/ruby" with your actual path for the Ruby shim.
112
147
 
113
- ## Usage
148
+ ### Using an MCP Proxy (Advanced)
114
149
 
115
- ### Starting the server
150
+ Claude Desktop and many other LLM clients only support STDIO mode communication, but you might want to use the HTTP/SSE capabilities of the server. An MCP proxy can bridge this gap:
116
151
 
117
- The Rails MCP Server can run in two modes:
118
-
119
- 1. **STDIO mode (default)**: Communicates over standard input/output for direct integration with clients like Claude Desktop.
120
- 2. **HTTP mode**: Runs as an HTTP server with JSON-RPC and Server-Sent Events (SSE) endpoints.
152
+ 1. Start the Rails MCP Server in HTTP mode:
121
153
 
122
154
  ```bash
123
- # Start in default STDIO mode
124
- rails-mcp-server
125
-
126
- # Start in HTTP mode on the default port (6029)
127
155
  rails-mcp-server --mode http
128
-
129
- # Start in HTTP mode on a custom port
130
- rails-mcp-server --mode http -p 8080
131
156
  ```
132
157
 
133
- When running in HTTP mode, the server provides two endpoints:
158
+ 2. Install and run an MCP proxy. There are several implementations available in different languages. An MCP proxy allows a client that only supports STDIO communication to communicate via HTTP SSE. Here's an example using a JavaScript-based MCP proxy:
134
159
 
135
- - JSON-RPC endpoint: `http://localhost:<port>/mcp/messages`
136
- - SSE endpoint: `http://localhost:<port>/mcp/sse`
160
+ ```bash
161
+ # Install the Node.js based MCP proxy
162
+ npm install -g mcp-remote
137
163
 
138
- ### Logging Options
164
+ # Run the proxy, pointing to your running Rails MCP Server
165
+ npx mcp-remote http://localhost:6029/mcp/sse
166
+ ```
139
167
 
140
- The server logs to a file in the `./log` directory by default. You can customize logging with these options:
168
+ 3. Configure Claude Desktop (or other LLM client) to use the proxy instead of connecting directly to the server:
141
169
 
142
- ```bash
143
- # Set the log level (debug, info, error)
144
- rails-mcp-server --log-level debug
170
+ ```json
171
+ {
172
+ "mcpServers": {
173
+ "railsMcpServer": {
174
+ "command": "npx",
175
+ "args": ["mcp-remote", "http://localhost:6029/mcp/sse"]
176
+ }
177
+ }
178
+ }
145
179
  ```
146
180
 
181
+ This setup allows STDIO-only clients to communicate with the Rails MCP Server through the proxy, benefiting from the HTTP/SSE capabilities while maintaining client compatibility.
182
+
147
183
  ## How the Server Works
148
184
 
149
185
  The Rails MCP Server implements the Model Context Protocol using either:
@@ -151,7 +187,7 @@ The Rails MCP Server implements the Model Context Protocol using either:
151
187
  - **STDIO mode**: Reads JSON-RPC 2.0 requests from standard input and returns responses to standard output.
152
188
  - **HTTP mode**: Provides HTTP endpoints for JSON-RPC 2.0 requests and Server-Sent Events.
153
189
 
154
- Each request includes a sequence number to match requests with responses, as defined in the MCP specification.
190
+ Each request includes a sequence number to match requests with responses, as defined in the MCP specification. The server maintains project context and provides Rails-specific analysis capabilities across multiple codebases.
155
191
 
156
192
  ## Available Tools
157
193
 
@@ -163,7 +199,7 @@ The server provides the following tools for interacting with Rails projects:
163
199
 
164
200
  **Parameters:**
165
201
 
166
- - `project_name`: (String, required) Name of the project to switch to, as defined in the projects.yml file
202
+ - `project_name`: (String, required) Name of the project as defined in the projects.yml file (case-sensitive)
167
203
 
168
204
  #### Examples
169
205
 
@@ -179,7 +215,7 @@ I'd like to analyze my "blog" application. Please switch to that project first.
179
215
  Switch to the "ecommerce" project and give me a summary of the codebase.
180
216
  ```
181
217
 
182
- ### 2. `get_project_info`
218
+ ### 2. `project_info`
183
219
 
184
220
  **Description:** Retrieve comprehensive information about the current Rails project, including Rails version, directory structure, API-only status, and overall project organization. Useful for initial project exploration and understanding the codebase structure.
185
221
 
@@ -205,8 +241,8 @@ I'd like to understand the high-level architecture of this project. Can you prov
205
241
 
206
242
  **Parameters:**
207
243
 
208
- - `directory`: (String, optional) Directory path relative to the project root (e.g., 'app/models', 'config')
209
- - `pattern`: (String, optional) File pattern using glob syntax (e.g., '.rb' for Ruby files, '.erb' for ERB templates)
244
+ - `directory`: (String, optional) Directory path relative to the project root (e.g., 'app/models', 'config'). Leave empty to list files at the root.
245
+ - `pattern`: (String, optional) File pattern using glob syntax (e.g., '*.rb' for Ruby files, '*.erb' for ERB templates, '*_controller.rb' for controllers)
210
246
 
211
247
  #### Examples
212
248
 
@@ -232,7 +268,7 @@ List all the JavaScript files in the app/javascript directory.
232
268
 
233
269
  **Parameters:**
234
270
 
235
- - `path`: (String, required) File path relative to the project root (e.g., 'app/models/user.rb', 'config/routes.rb')
271
+ - `path`: (String, required) File path relative to the project root (e.g., 'app/models/user.rb', 'config/routes.rb'). Use list_files first if you're not sure about the exact path.
236
272
 
237
273
  #### Examples
238
274
 
@@ -272,13 +308,13 @@ I need to understand the API endpoints available in this project. Can you list t
272
308
  Show me the routing configuration for this Rails app so I can see how the URLs are structured.
273
309
  ```
274
310
 
275
- ### 6. `analyze_models`
311
+ ### 6. `analize_models`
276
312
 
277
313
  **Description:** Retrieve detailed information about Active Record models in the project. When called without parameters, lists all model files. When a specific model is specified, returns its schema, associations (has_many, belongs_to, has_one), and complete source code.
278
314
 
279
315
  **Parameters:**
280
316
 
281
- - `model_name`: (String, optional) Class name of a specific model to get detailed information for (e.g., 'User', 'Product'). Use CamelCase, not snake_case.
317
+ - `model_name`: (String, optional) Class name of a specific model to get detailed information for (e.g., 'User', 'Product'). Use CamelCase, not snake_case. If omitted, returns a list of all models.
282
318
 
283
319
  #### Examples
284
320
 
@@ -304,7 +340,7 @@ What are all the models in this application, and can you then show me details fo
304
340
 
305
341
  **Parameters:**
306
342
 
307
- - `table_name`: (String, optional) Database table name to get detailed schema information for (e.g., 'users', 'products'). Use snake_case, plural form.
343
+ - `table_name`: (String, optional) Database table name to get detailed schema information for (e.g., 'users', 'products'). Use snake_case, plural form. If omitted, returns complete database schema.
308
344
 
309
345
  #### Examples
310
346
 
@@ -338,6 +374,14 @@ I need to understand the database design. Can you first list all tables and then
338
374
  Can you analyze the Users controller and its views to help me understand the UI flow?
339
375
  ```
340
376
 
377
+ ```
378
+ Show me how the ProductsController connects to its views and what actions are available.
379
+ ```
380
+
381
+ ```
382
+ I want to understand the entire controller-view structure of this application.
383
+ ```
384
+
341
385
  ### 9. `analyze_environment_config`
342
386
 
343
387
  **Description:** Analyze environment configurations to identify inconsistencies, security issues, and missing variables across environments.
@@ -350,14 +394,70 @@ Can you analyze the Users controller and its views to help me understand the UI
350
394
  Can you analyze the environment configurations to find any security issues or missing environment variables?
351
395
  ```
352
396
 
353
- ## Integration with LLM Clients
397
+ ```
398
+ Check the configuration files for any inconsistencies between development and production environments.
399
+ ```
354
400
 
355
- This server is designed to be integrated with LLM clients that support the Model Context Protocol, such as Claude Desktop or other MCP-compatible applications.
356
- To use with an MCP client:
401
+ ### 10. `load_guide`
357
402
 
358
- 1. Start the Rails MCP Server (it will use STDIO mode by default)
359
- 1. Connect your MCP-compatible client to the server
360
- 1. The client will be able to use the available tools to interact with your Rails projects
403
+ **Description:** Load documentation guides from Rails, Turbo, Stimulus, Kamal, or Custom. Use this to get guide content for context in conversations.
404
+
405
+ **Parameters:**
406
+
407
+ - `guides`: (String, required) The guides library to search: 'rails', 'turbo', 'stimulus', 'kamal', or 'custom'
408
+ - `guide`: (String, optional) Specific guide name to load. If not provided, returns available guides list.
409
+
410
+ #### Examples
411
+
412
+ ```
413
+ Can you load the Rails getting started guide?
414
+ ```
415
+
416
+ ```
417
+ Show me the available Turbo guides and then load the one about Turbo Frames.
418
+ ```
419
+
420
+ ```
421
+ I need help with Stimulus. Can you load the hello_stimulus guide?
422
+ ```
423
+
424
+ ```
425
+ Load the Kamal installation guide so I can understand deployment options.
426
+ ```
427
+
428
+ ## Resources and Documentation
429
+
430
+ The Rails MCP Server provides access to comprehensive documentation through both the `load_guide` tool and direct MCP resource access. You can access official guides for Rails, Turbo, Stimulus, and Kamal, as well as import your own custom documentation.
431
+
432
+ ### Available Resource Categories
433
+
434
+ - **Rails Guides**: Official Ruby on Rails 8.0.2 documentation
435
+ - **Turbo Guides**: Official Turbo (Hotwire) framework documentation
436
+ - **Stimulus Guides**: Official Stimulus JavaScript framework documentation
437
+ - **Kamal Guides**: Official Kamal deployment tool documentation
438
+ - **Custom Guides**: Your imported markdown files
439
+
440
+ ### Getting Started with Resources
441
+
442
+ Before using resources, you need to download them:
443
+
444
+ ```bash
445
+ # Download Rails guides
446
+ rails-mcp-server-download-resources rails
447
+
448
+ # Download Turbo guides
449
+ rails-mcp-server-download-resources turbo
450
+
451
+ # Import custom markdown files
452
+ rails-mcp-server-download-resources --file /path/to/your/docs/
453
+ ```
454
+
455
+ ### Resource Access Methods
456
+
457
+ 1. **Tool-based access**: Use the `load_guide` tool in conversations
458
+ 2. **Direct resource access**: MCP clients can query resources using URI patterns like `rails://guides/{guide_name}`
459
+
460
+ For complete information about downloading, managing, and using resources, see the [Resources Guide](docs/RESOURCES.md).
361
461
 
362
462
  ## Testing and Debugging
363
463
 
@@ -365,7 +465,7 @@ The easiest way to test and debug the Rails MCP Server is by using the MCP Inspe
365
465
 
366
466
  To use MCP Inspector with Rails MCP Server:
367
467
 
368
- ```
468
+ ```bash
369
469
  # Install and run MCP Inspector with your Rails MCP Server
370
470
  npm -g install @modelcontextprotocol/inspector
371
471
 
@@ -375,8 +475,8 @@ npx @modelcontextprotocol/inspector /path/to/rails-mcp-server
375
475
  This will:
376
476
 
377
477
  1. Start your Rails MCP Server in HTTP mode
378
- 1. Launch the MCP Inspector UI in your browser (default port: 6274)
379
- 1. Set up an MCP Proxy server (default port: 6277)
478
+ 2. Launch the MCP Inspector UI in your browser (default port: 6274)
479
+ 3. Set up an MCP Proxy server (default port: 6277)
380
480
 
381
481
  In the MCP Inspector UI, you can:
382
482
 
@@ -387,6 +487,16 @@ In the MCP Inspector UI, you can:
387
487
 
388
488
  The Inspector UI provides an intuitive interface to interact with your MCP server, making it easy to test and debug your Rails MCP Server implementation.
389
489
 
490
+ ## Integration with LLM Clients
491
+
492
+ This server is designed to be integrated with LLM clients that support the Model Context Protocol, such as Claude Desktop or other MCP-compatible applications.
493
+
494
+ To use with an MCP client:
495
+
496
+ 1. Start the Rails MCP Server (it will use STDIO mode by default)
497
+ 2. Connect your MCP-compatible client to the server
498
+ 3. The client will be able to use the available tools to interact with your Rails projects
499
+
390
500
  ## License
391
501
 
392
502
  This Rails MCP server is released under the MIT License, a permissive open-source license that allows for free use, modification, distribution, and private use.
@@ -397,7 +507,7 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
397
507
 
398
508
  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
399
509
 
400
- 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.
510
+ 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 IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
401
511
 
402
512
  ## Contributing
403
513