npm package: @rogercampos/blueprint-mcp-server
Description: MCP server providing documentation for Blueprint Gamma components and features
Author: Roger Campos
Latest version: 0.1.1

# Blueprint MCP Server

A Model Context Protocol (MCP) server that provides comprehensive documentation for Blueprint Gamma components and features. This enables AI assistants like Claude to access up-to-date Blueprint documentation during conversations.

## What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely access external data sources and tools. This Blueprint MCP server exposes Blueprint's documentation through a standardized interface that can be used by any MCP-compatible client.

## Features

This MCP server provides the following tools:

- **search_components** - Search Blueprint components by name, category, or description
- **list_all_components** - List all available Blueprint components, optionally filtered by category
- **get_component** - Get detailed documentation for a specific component
- **list_features** - List all available Blueprint features
- **get_feature** - Get detailed documentation for a specific feature

## Installation

### Global Installation (Recommended for npx usage)

```bash
npm install -g @rogercampos/blueprint-mcp-server
```

### Local Installation in a Project

```bash
npm install @rogercampos/blueprint-mcp-server
```

## Usage

### With Claude Desktop

Add the server to your Claude Desktop configuration file:

**On macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**On Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "blueprint": {
      "command": "npx",
      "args": ["@rogercampos/blueprint-mcp-server"]
    }
  }
}
```

After adding this configuration, restart Claude Desktop. You should now be able to ask Claude questions about Blueprint components and features.

### With Other MCP Clients

The server communicates over stdio, so you can integrate it with any MCP-compatible client:

```bash
npx @rogercampos/blueprint-mcp-server
```

### Testing with MCP Inspector

You can test the server using the MCP Inspector tool:

```bash
npx @modelcontextprotocol/inspector npx @rogercampos/blueprint-mcp-server
```

This will open a web interface where you can interact with the server and test all available tools.

## Development

### Setup

```bash
# Clone the repository
cd mcp_server

# Install dependencies
npm install

# Build the project
npm run build
```

### Testing Locally

```bash
# Build and run
npm run dev

# Or use the inspector
npx @modelcontextprotocol/inspector node build/index.js
```

### Project Structure

```
mcp_server/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── utils.ts              # Shared utilities and type definitions
│   └── tools/                # Tool implementations
│       ├── searchComponents.ts
│       ├── listAllComponents.ts
│       ├── getComponent.ts
│       ├── listFeatures.ts
│       └── getFeature.ts
├── docs/                     # YAML documentation files
│   ├── components/           # Component documentation
│   ├── features/             # Feature documentation
│   ├── stimulus_controllers/ # Stimulus controller docs
│   └── setup/                # Setup guides
├── package.json
├── tsconfig.json
└── README.md
```

## Available Tools

### search_components

Search Blueprint components by name, category, or description.

**Arguments:**
- `query` (required): Search query - component name, keyword, or feature
- `category` (optional): Filter by category: form, layout, overlay, feedback

**Example:**
```json
{
  "query": "button",
  "category": "form"
}
```

### list_all_components

List all available Blueprint components, optionally filtered by category.

**Arguments:**
- `category` (optional): Filter by category: form, layout, overlay, feedback

**Example:**
```json
{
  "category": "form"
}
```

### get_component

Get detailed documentation for a specific Blueprint component.

**Arguments:**
- `slug` (required): Component slug (e.g., 'button', 'input', 'dialog')

**Example:**
```json
{
  "slug": "button"
}
```

### list_features

List all available Blueprint features with descriptions.

**Arguments:** None

### get_feature

Get detailed documentation for a specific Blueprint feature.

**Arguments:**
- `slug` (required): Feature slug (e.g., 'email_tracking', 'datatables', 'turnstile')

**Example:**
```json
{
  "slug": "email_tracking"
}
```

## Documentation Format

All documentation is stored in YAML files under the `docs/` directory:

- **Components** (`docs/components/*.yml`): UI component documentation including parameters, usage examples, and best practices
- **Features** (`docs/features/*.yml`): Non-UI functionality documentation including setup steps, configuration, and usage
- **Stimulus Controllers** (`docs/stimulus_controllers/*.yml`): JavaScript controller documentation
- **Setup Guides** (`docs/setup/*.yml`): Installation and configuration guides

## License

MIT

## Related Projects

- [Blueprint Gamma](https://github.com/rogercampos/blueprint) - The main Blueprint gem
- [Model Context Protocol](https://modelcontextprotocol.io) - The MCP specification