npm package: @opencosmos/mcp
Description: Model Context Protocol server for OpenCosmos/UI - discover and integrate components with AI assistants
Author: Shalom Ormsby
Latest version: 0.8.3

# @thesage/mcp

**Model Context Protocol server for Sage Design Engine**

Enable AI assistants like Claude Desktop, Cursor, and VS Code to browse, search, and install Sage Design Engine components directly through natural language.

## Features

- 🔍 **Browse all 100 components** across 11 functional categories
- 🔎 **Semantic search** by keywords, use cases, or functionality
- 📖 **Detailed component info** including props, dependencies, and examples
- 📦 **Installation instructions** with all required dependencies
- ⏏️ **Eject components** — get transformed source code ready to paste into any project
- 🤖 **AI-native** - Built specifically for LLM interaction

## Installation

### Quick Start

```bash
pnpm add -D @thesage/mcp
# or
npm install --save-dev @thesage/mcp
# or
yarn add -D @thesage/mcp
```

### MCP Client Configuration

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sds": {
      "command": "npx",
      "args": ["@thesage/mcp"]
    }
  }
}
```

Restart Claude Desktop to activate.

#### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "sds": {
      "command": "npx",
      "args": ["@thesage/mcp"]
    }
  }
}
```

#### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "sds": {
      "command": "npx",
      "args": ["@thesage/mcp"]
    }
  }
}
```

## Available Tools

The MCP server provides 8 tools for AI interaction:

### 1. `list_components`

List all available components, optionally filtered by category.

**Parameters:**
- `category` (optional): Filter by `actions`, `forms`, `navigation`, `overlays`, `feedback`, `data-display`, `layout`, `backgrounds`, `cursor`, `motion`, or `blocks`

**Example AI prompts:**
- "Show me all Sage Design Engine components"
- "List all form components"
- "What overlay components are available?"

### 2. `search_components`

Search for components by keywords, descriptions, or use cases.

**Parameters:**
- `query` (required): Search term

**Example AI prompts:**
- "Find components for date selection"
- "Search for dropdown components"
- "Show me components for displaying user profiles"

### 3. `get_component`

Get detailed information about a specific component.

**Parameters:**
- `name` (required): Component name (case-insensitive, accepts PascalCase or kebab-case)

**Example AI prompts:**
- "Tell me about the Button component"
- "What props does the DataTable have?"
- "Show me details for the date-picker"

### 4. `install_component`

Get installation instructions for a component.

**Parameters:**
- `name` (required): Component name to install

**Example AI prompts:**
- "Install the Dialog component"
- "How do I add the DataTable to my project?"
- "Show me how to install the ComboBox"

### 5. `get_app_shell`

Get a complete, ready-to-use app shell with ThemeProvider, Toaster, Tailwind config, and globals.css.

**Parameters:**
- `framework` (optional): `"nextjs"` or `"vite"` (default: `"vite"`)
- `theme` (optional): `"studio"`, `"terra"`, or `"volt"` (default: `"studio"`)

### 6. `get_examples`

Get usage examples for a specific component.

**Parameters:**
- `name` (required): Component name

### 7. `get_audit_checklist`

Returns a post-generation checklist to verify correct SDE usage (providers, styling, accessibility, imports).

### 8. `eject_component`

Eject a component's source code for full customization. Returns the **actual transformed source code** with internal imports rewritten to package-level imports — ready to save directly into the user's project.

**Parameters:**
- `name` (required): Component name (e.g., `"Button"`, `"Dialog"`)
- `targetDir` (optional): Target directory (default: `"src/components/ui"`)

**What it returns:**
- Transformed component source code (ready to save as `.tsx`)
- `cn()` utility code if needed
- List of npm dependencies to install
- Import update instructions

**Example AI prompts:**
- "Eject the Button component so I can customize it"
- "I need the Dialog source code in my project"
- "Give me the Card component source for local modification"

## Component Categories

The Sage Design Engine organizes components functionally (not atomically):

- **Actions** (3) - Interactive elements that trigger behaviors
- **Forms** (11) - Input controls for data collection
- **Navigation** (6) - Moving through content and hierarchy
- **Overlays** (9) - Contextual content above the main UI
- **Feedback** (5) - System state communication
- **Data Display** (6) - Presenting information visually
- **Layout** (8) - Spatial organization

## Usage Examples

Once configured, you can interact with the server through your AI assistant:

### Browse Components

> "Show me all components in the Sage Design Engine"

The AI will use `list_components` to display all 100 components organized by category.

### Search for Specific Functionality

> "I need a component for selecting dates"

The AI will use `search_components` with query "date" and find:
- Calendar
- DatePicker

### Get Component Details

> "Tell me about the Button component"

The AI will use `get_component` to show:
- Description
- Use cases
- Dependencies
- Import statements
- Documentation link

### Install a Component

> "Add the Dialog component to my project"

The AI will use `install_component` to provide:
- Package installation commands
- Peer dependency requirements
- Import examples
- Usage code

## Architecture

The MCP server consists of:

1. **Component Registry** (`src/registry.ts`) - Metadata for all 100 @thesage/ui components
2. **MCP Server** (`src/index.ts`) - Model Context Protocol implementation with 8 tools
3. **Eject Engine** - Reads component source, transforms imports, returns ready-to-use code

Registry data is statically defined. The eject tool reads source files from the monorepo or `node_modules`.

## Development

### Build

```bash
pnpm build
```

### Test Locally

```bash
pnpm start
```

The server runs in stdio mode, communicating via stdin/stdout per the MCP specification.

## Documentation

- **Full Documentation**: https://thesage.dev/
- **GitHub**: https://github.com/shalomormsby/sage-design-engine
- **MCP Specification**: https://modelcontextprotocol.io/

## Support

For issues or questions:
- GitHub Issues: https://github.com/shalomormsby/sage-design-engine/issues
- Documentation: https://thesage.dev/#mcp-server

## License

MIT © Shalom Ormsby

---

**Part of the [Sage Design Engine](https://thesage.dev/) - Build lovable products at AI speed.**