# Rails Blocks MCP

Use Rails Blocks with AI coding agents through a local MCP server backed by the Rails Blocks CLI.

The MCP server lets agents discover docs, inspect examples, and install components. It runs locally in your editor and keeps free component reads on the public static registry.

## How It Works

1. Your AI assistant asks Rails Blocks for component help.
2. The Rails Blocks MCP server runs locally through the `rails-blocks` CLI.
3. Free components come from the public Rails Blocks registry.
4. Pro components use your Rails Blocks access token.

## Install

Install both the CLI and MCP package. The MCP server expects the `rails-blocks` executable to be available on your path.

Using npm:

```bash
gem install rails-blocks-cli
npm install -g @rails-blocks/mcp
```

Using yarn:

```bash
gem install rails-blocks-cli
yarn global add @rails-blocks/mcp
```

## Configure Your MCP Client

Add the Rails Blocks MCP server to your client configuration. If your CLI executable is not on the default path, set `RAILS_BLOCKS_CLI`.

```json
{
  "mcpServers": {
    "rails-blocks": {
      "command": "rails-blocks-mcp",
      "env": {
        "RAILS_BLOCKS_CLI": "rails-blocks",
        "RAILS_BLOCKS_API_TOKEN": "rb_your_pro_token"
      }
    }
  }
}
```

`RAILS_BLOCKS_API_TOKEN` is only needed for Pro docs, examples, and installs.

## Available Tools

| Tool | Description |
| ---- | ----------- |
| `rails_blocks_list_components` | List all, free, or Pro components from the registry. |
| `rails_blocks_search_docs` | Find relevant components by name or keyword. |
| `rails_blocks_get_docs` | Fetch free or Pro docs, depending on token access. |
| `rails_blocks_get_examples` | Return usage examples for a component. |
| `rails_blocks_install_component` | Install one component and its required Stimulus controllers. Supports `path`, `stimulusPath`, `dryRun`, and `force`. |
| `rails_blocks_install_all_components` | Install all, free, or Pro components matching a filter. Agents should dry-run first unless writes are explicitly approved. |
| `rails_blocks_update_stimulus_controllers` | Diff or update Rails Blocks Stimulus controllers directly. |

## Authorize Pro Access

Pro access is handled with access tokens. Run the CLI login once, approve the code in your browser or email, then your MCP server can use Pro docs and packages without sharing your password or browser session.

```bash
rails-blocks login
rails-blocks login --email you@example.com
rails-blocks doctor
```

Prefer not to store a token in your MCP config? Use `rails-blocks login` once instead. The CLI stores the approved token locally in `~/.rails_blocks/config.json`, and the MCP server reuses it.

## AI Instructions

When using this page as context:

- Treat MCP as an agent-facing wrapper around the Rails Blocks CLI.
- Prefer read-only discovery tools before install tools.
- Dry-run installs before writing files unless the user explicitly approves writes.
- If installation, styling, JavaScript behavior, or dependency setup fails, send the user through https://railsblocks.com/docs/installation before retrying component installs.
- Use `rails_blocks_install_all_components` when the user asks to install every component or every free/Pro component.
- Use `rails_blocks_update_stimulus_controllers` when the user specifically asks to diff or refresh Stimulus controllers.
- Prefer `path` and `stimulusPath` tool arguments instead of manually moving generated files after install.
- For Pro components, verify `RAILS_BLOCKS_API_TOKEN` is set or `rails-blocks login` has been completed.
- If configuration fails, run `rails-blocks doctor` before changing MCP client config.