使用说明

Rails Dev MCP Server

A self-learning MCP (Model Context Protocol) server for Rails + React + PostgreSQL development. This server provides guided workflows, code generation from templates, and learns from successful implementations to improve its library over time.

Features

Workflow Engine: Guides users through code generation with questions and options
Pattern Library: Pre-built patterns for common Rails/React development tasks
Template Engine: EJS-based templates with Rails/React convention helpers
Code Analysis: Parse and analyze existing codebases to extract patterns
Learning Engine: Learn from successful implementations to improve the library
PostgreSQL Integration: Query and analyze your database directly

Installation

npm install
npm run build

Usage

As an MCP Server

Claude Code

Do not add mcpServers to ~/.claude/settings.json. Claude Code does not read MCP server definitions from that file. Entries placed there are ignored silently — no warning is printed, and the server never appears in claude mcp list.

# available in every project
claude mcp add rails-dev --scope user \
  --env RAILS_MCP_LIBRARY=/path/to/rails-dev-mcp/library \
  -- node /path/to/rails-dev-mcp/dist/index.js

# or scoped to the current project only (omit --scope)
claude mcp add rails-dev \
  --env RAILS_MCP_LIBRARY=/path/to/rails-dev-mcp/library \
  -- node /path/to/rails-dev-mcp/dist/index.js

Verify with claude mcp list — it should report rails-dev ... ✔ Connected.

To share the configuration with your team, use --scope project, which writes a .mcp.json at the repo root that can be committed:

{
  "mcpServers": {
    "rails-dev": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/rails-dev-mcp/dist/index.js"],
      "env": {
        "RAILS_MCP_LIBRARY": "/path/to/rails-dev-mcp/library"
      }
    }
  }
}

RAILS_MCP_LIBRARY is required unless you pass --library; without it the server falls back to ./library relative to the process working directory, which is rarely what you want when the client launches it. Point it at the library/ directory inside this repo.

Other MCP clients

Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), and VS Code (.vscode/mcp.json) all take the same server definition shown in the .mcp.json example above, under each client's own configuration key.

Database tools

The query_database, list_tables, describe_table, analyze_query, and table_stats tools require a PostgreSQL connection. Every other tool works without one.

The connection can come from environment variables, a YAML config file, or both.

Environment variables alone are usually simplest for a client-launched server:

claude mcp add rails-dev --scope user \
  --env RAILS_MCP_LIBRARY=/path/to/rails-dev-mcp/library \
  --env RAILS_MCP_DB_HOST=localhost \
  --env RAILS_MCP_DB_PORT=5432 \
  --env RAILS_MCP_DB_NAME=myapp_development \
  --env RAILS_MCP_DB_USER=postgres \
  -- node /path/to/rails-dev-mcp/dist/index.js

Alternatively, uncomment the database block in config/default.yml and point at it with --config or RAILS_MCP_CONFIG:

database:
  host: localhost
  port: 5432
  user: postgres
  password: password
  database: myapp_development

When both are present the environment wins field by field — useful for keeping a committed config with shared defaults and overriding only the database name per checkout. See Environment Variables for the full precedence rules.

If neither source supplies a user and database name, the pool is never constructed and the database tools fail with Database not configured.

Prefer a read-only role. query_database accepts SELECT statements, but a restricted grant enforces that at the database rather than relying on the tool.

Command Line Options

node dist/index.js --help

Options:
  --library <path>  Path to the library directory (default: ./library)
  --config <path>   Path to configuration file (default: ./config/default.yml)
  --help            Show help

Environment Variables

Variable	Purpose	Default	Precedence
`RAILS_MCP_LIBRARY`	Library directory path	`./library`	overridden by `--library`
`RAILS_MCP_CONFIG`	Config file path	none	overridden by `--config`
`RAILS_MCP_DB_HOST`	PostgreSQL host	`localhost`	overrides config file
`RAILS_MCP_DB_PORT`	PostgreSQL port	`5432`	overrides config file
`RAILS_MCP_DB_USER`	PostgreSQL user	none — required	overrides config file
`RAILS_MCP_DB_PASS`	PostgreSQL password	none	overrides config file
`RAILS_MCP_DB_NAME`	PostgreSQL database name	none — required	overrides config file

The RAILS_MCP_DB_* variables merge over the database block in the config file field by field, so a committed config can hold shared defaults while each environment overrides only what differs. Setting none of them leaves the config file in sole control.

A user and database name are required — host and port fall back to localhost:5432, but there is no sensible default for the other two. If neither source supplies them, a warning is written to stderr and the database tools stay unconfigured. A non-numeric or out-of-range RAILS_MCP_DB_PORT is ignored with a warning rather than silently coercing to NaN.

Available Tools

Workflow Tools

identify_intent - Match user intent to patterns
start_workflow - Begin a guided workflow
answer_workflow_step - Answer workflow questions
execute_workflow - Generate code from completed workflow
cancel_workflow - Cancel active workflow

Library Tools

search_library - Search patterns, templates, snippets
get_pattern - Get pattern definition
get_template - Get template with content
get_snippet - Get snippet with variable substitution
list_patterns - List all patterns
list_templates - List all templates
list_snippets - List all snippets

Analysis Tools

detect_project_context - Analyze project structure
analyze_codebase - Full codebase analysis
analyze_models - Analyze Rails models
analyze_components - Analyze React components
analyze_controllers - Analyze Rails controllers
analyze_styles - Analyze CSS/styling
batch_analyze - Analyze multiple projects

Learning Tools

analyze_implementation - Propose new patterns from code
propose_contribution - Submit new pattern/template/snippet
review_contributions - List pending contributions
approve_contribution - Approve and add to library
reject_contribution - Reject contribution

Database Tools

query_database - Run SELECT queries
list_tables - List database tables
describe_table - Get table structure
analyze_query - EXPLAIN ANALYZE
table_stats - Get table statistics

Generation Tools

generate_from_template - Generate single file
generate_multiple - Generate multiple files
generate_from_pattern - Generate all pattern files
render_snippet - Render snippet with variables

Included Patterns

crud-resource - Full CRUD with model, controller, React components
nested-resource - Comments, replies, child resources
user-authentication - Login, signup, sessions
file-upload - Active Storage attachments
search-filter - Search and filtering
pagination - Paginated lists
api-endpoint - JSON API endpoints
background-job - Sidekiq/ActiveJob
authorization - Role-based permissions
bootstrap-to-tailwind - CSS migration

Library Structure

library/
├── patterns/
│   ├── index.json
│   └── {pattern-id}/
│       └── manifest.json
├── templates/
│   ├── index.json
│   ├── {template-id}.json
│   └── {template-id}.ejs
├── snippets/
│   ├── index.json
│   └── {snippet-id}.json
└── learned/
    ├── pending_review/
    ├── approved/
    └── rejected/

Extending the Library

Adding a Pattern

Create a new directory under library/patterns/ with a manifest.json:

{
  "id": "my-pattern",
  "name": "My Pattern",
  "description": "Description of the pattern",
  "category": "full-stack",
  "triggers": ["keywords", "to match"],
  "workflow": {
    "id": "wf-my-pattern",
    "steps": [...]
  },
  "templates": ["template-ids"],
  "snippets": ["snippet-ids"],
  "instructions": ["Post-generation steps"],
  "version": "1.0.0",
  "tags": ["tags"]
}

Adding a Template

Create JSON metadata and EJS template files:

{
  "id": "my-template",
  "name": "My Template",
  "category": "model",
  "language": "ruby",
  "filePath": "templates/my-template.ejs",
  "outputPath": "app/models/<%= underscore(name) %>.rb",
  "variables": [
    {"name": "name", "type": "string", "required": true}
  ]
}

Adding a Snippet

{
  "id": "my-snippet",
  "name": "My Snippet",
  "category": "validation",
  "language": "ruby",
  "code": "validates {{field}}, presence: true",
  "variables": [
    {"name": "field", "description": "Field name"}
  ]
}

Development

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

License

MIT