mozaic-mcp-server 1.0.2 → 1.1.0

package/INSTALLATION.md

@@ -1,138 +1,169 @@
 # Installation Guide
 
-Complete setup guide for Mozaic Design System MCP Server and Skills.
+This package provides **two installation modes**: Skills (recommended) and MCP Server.
 
-## Overview
+## Quick Install (Skills Mode - Recommended)
 
-The Mozaic ecosystem has two components:
+**Install skills for Claude Code:**
 
-1. **MCP Server** - Provides database access and tools (required)
-2. **Skills** - Provides interactive workflows (optional, but recommended)
+```bash
+npx mozaic-mcp-server install-skills
+```
 
-## Complete Setup (Recommended)
+That's it! Skills are now available in Claude Code.
 
-### Step 1: Install Skills
+## Alternative Install (MCP Server Mode)
 
-**Using npx** (fastest):
-```bash
-npx mozaic-mcp-server install
-```
+**Install as MCP server for Claude Desktop:**
 
-This installs 5 skills to `~/.claude/skills/`:
-- `mozaic-vue-builder`
-- `mozaic-react-builder`
-- `mozaic-design-tokens`
-- `mozaic-css-utilities`
-- `mozaic-icons`
-
-### Step 2: Configure MCP Server
-
-Add the MCP server to your Claude Code settings:
-
-**Option A: Using npx** (no installation needed):
-```json
-{
-  "mcpServers": {
-    "mozaic": {
-      "command": "npx",
-      "args": ["mozaic-mcp-server"]
-    }
-  }
-}
+```bash
+npx mozaic-mcp-server install-mcp
 ```
 
-**Option B: Using local installation**:
-```bash
-# Clone and build
-git clone https://github.com/merzoukemansouri/adeo-mozaic-mcp.git
-cd adeo-mozaic-mcp
-pnpm install
-pnpm build
+This adds the MCP server to Claude Desktop config. Restart Claude Desktop after installation.
 
-# Configure in Claude Code settings
-```
+## View All Commands
 
-```json
-{
-  "mcpServers": {
-    "mozaic": {
-      "command": "node",
-      "args": ["/absolute/path/to/adeo-mozaic-mcp/dist/index.js"]
-    }
-  }
-}
-```
+**Show help menu:**
 
-**Option C: Using global installation**:
 ```bash
-npm install -g mozaic-mcp-server
-
-# Configure in Claude Code settings
+npx mozaic-mcp-server install
 ```
 
-```json
-{
-  "mcpServers": {
-    "mozaic": {
-      "command": "mozaic-mcp-server"
-    }
-  }
-}
-```
+## What Gets Installed
 
-### Step 3: Verify Installation
+### Skills Mode (`install-skills`)
 
-Restart Claude Code and verify:
+The installer:
+1. Copies 5 skills to `~/.claude/skills/`
+2. Copies the Mozaic database to `~/.claude/mozaic.db`
+3. Makes skills immediately available (no configuration needed)
 
-1. **MCP Server**: Check that tools are available (e.g., `mcp__mozaic__list_components`)
-2. **Skills**: Skills should appear in skills list and activate automatically
+**Installed skills:**
+- `mozaic-vue-builder` - Interactive Vue 3 component generator
+- `mozaic-react-builder` - Interactive React/TSX component generator
+- `mozaic-design-tokens` - Design tokens and styling expert
+- `mozaic-css-utilities` - CSS utilities and layout systems
+- `mozaic-icons` - Icon search and integration
 
-## Skills Only (Lightweight)
+**Database location:** `~/.claude/mozaic.db` (8.3 MB)
 
-If you only want the skills (without MCP server):
+**Total size:** ~15 MB
 
-```bash
-npx mozaic-mcp-server install
-```
+### MCP Server Mode (`install-mcp`)
+
+The installer:
+1. Adds MCP server configuration to `~/.claude/config.json`
+2. Enables 11 MCP tools in Claude Desktop
+3. Requires Claude Desktop restart
 
-**Note**: Skills will reference MCP tools, but won't function without the MCP server configured.
+**Database location:** Uses the package's built-in database (not copied)
 
-## MCP Server Only
+## Verify Installation
 
-If you only want the MCP server:
+Check that files were installed:
 
 ```bash
-# Using npx
-npx mozaic-mcp-server
-
-# Or install locally
-git clone https://github.com/merzoukemansouri/adeo-mozaic-mcp.git
-cd adeo-mozaic-mcp
-pnpm install
-pnpm build
-pnpm start
+# Check skills
+ls ~/.claude/skills/
+
+# Should show:
+# mozaic-vue-builder
+# mozaic-react-builder
+# mozaic-design-tokens
+# mozaic-css-utilities
+# mozaic-icons
+
+# Check database
+ls -lh ~/.claude/mozaic.db
+
+# Should show: mozaic.db (8.3M)
 ```
 
-Then configure in Claude Code settings (see Step 2 above).
+Skills will activate automatically in Claude Code based on context.
 
 ## Uninstallation
 
 ### Remove Skills
+
 ```bash
-npx mozaic-mcp-server uninstall
+npx mozaic-mcp-server uninstall-skills
 ```
 
-### Remove MCP Server Configuration
-Remove the `mozaic` entry from your Claude Code settings.
+This removes:
+- All 5 skills from `~/.claude/skills/`
+- Database from `~/.claude/mozaic.db`
+
+### Remove MCP Server
 
-### Remove Local Installation
 ```bash
-# If installed globally
-npm uninstall -g mozaic-mcp-server
+npx mozaic-mcp-server uninstall-mcp
+```
+
+This removes:
+- MCP server configuration from `~/.claude/config.json`
+- Requires Claude Desktop restart
+
+## How It Works
+
+### Skills Mode
+1. **Installation**: `npx mozaic-mcp-server install-skills` runs the installer
+2. **Skills**: Each skill contains a `skill.md` file and `scripts/` folder
+3. **Scripts**: Bash scripts query the SQLite database and return JSON
+4. **Database**: `~/.claude/mozaic.db` contains all Mozaic data (tokens, components, icons)
+5. **No Server**: Everything runs locally - no MCP server configuration needed
+
+### MCP Server Mode
+1. **Installation**: `npx mozaic-mcp-server install-mcp` updates Claude Desktop config
+2. **Server**: Runs as MCP server when Claude Desktop starts
+3. **Tools**: Provides 11 MCP tools for component info, tokens, icons, etc.
+4. **Database**: Uses package's built-in database
+
+## Architecture
 
-# If cloned locally
-rm -rf /path/to/adeo-mozaic-mcp
 ```
+~/.claude/
+├── skills/
+│   ├── mozaic-vue-builder/
+│   │   ├── skill.md
+│   │   └── scripts/
+│   │       ├── list-components.sh
+│   │       ├── get-component.sh
+│   │       ├── generate-component.sh
+│   │       └── get-install-info.sh
+│   ├── mozaic-react-builder/
+│   │   ├── skill.md
+│   │   └── scripts/ (same structure)
+│   ├── mozaic-design-tokens/
+│   │   ├── skill.md
+│   │   └── scripts/
+│   │       ├── get-tokens.sh
+│   │       └── search-docs.sh
+│   ├── mozaic-css-utilities/
+│   │   ├── skill.md
+│   │   └── scripts/
+│   │       ├── list-utilities.sh
+│   │       └── get-utility.sh
+│   └── mozaic-icons/
+│       ├── skill.md
+│       └── scripts/
+│           ├── search-icons.sh
+│           └── get-icon.sh
+└── mozaic.db (SQLite database)
+```
+
+## Database Contents
+
+The `mozaic.db` SQLite database contains:
+
+| Type                 | Count | Description                                                     |
+| -------------------- | ----- | --------------------------------------------------------------- |
+| **Design Tokens**    | 586   | Colors, typography, spacing, shadows, borders, screens, grid    |
+| **Vue Components**   | 52    | Props, slots, events, examples                                  |
+| **React Components** | 39    | Props, callbacks, examples                                      |
+| **Icons**            | 1,473 | SVG icons in 15 categories (354 unique, 5 sizes each)           |
+| **CSS Utilities**    | 6     | Flexy, Container, Margin, Padding, Ratio, Scroll (500+ classes) |
+| **Documentation**    | 281   | MDX pages with full-text search                                 |
 
 ## Troubleshooting
 
@@ -142,87 +173,129 @@ rm -rf /path/to/adeo-mozaic-mcp
    ```bash
    ls ~/.claude/skills/
    ```
-   Should show: `mozaic-vue-builder`, `mozaic-react-builder`, etc.
+   Should show 5 `mozaic-*` directories
 
 2. Restart Claude Code
 
-3. Check skill frontmatter in `.md` files
+3. Check skill activation - skills activate automatically based on context
 
-### MCP Tools Not Working
+### Database Not Found
 
-1. Verify MCP server configuration in Claude Code settings
+If skills report database errors:
 
-2. Test MCP server directly:
-   ```bash
-   npx mozaic-mcp-server
-   # Should start without errors
-   ```
+```bash
+# Check database exists
+ls -lh ~/.claude/mozaic.db
 
-3. Check Claude Code logs for MCP connection errors
+# If missing, reinstall
+npx mozaic-mcp-server install-skills
+```
+
+### Shell Scripts Not Executable
+
+If you see permission errors:
+
+```bash
+# Make all scripts executable
+find ~/.claude/skills/mozaic-*/scripts -name "*.sh" -exec chmod +x {} \;
+```
 
 ### Database Errors
 
-If using local installation:
+If the database is corrupted:
 
 ```bash
-cd adeo-mozaic-mcp
-pnpm build  # Rebuilds database
+# Uninstall and reinstall
+npx mozaic-mcp-server uninstall-skills
+npx mozaic-mcp-server install-skills
 ```
 
-If using npx, the database is bundled with the package.
+## Requirements
 
-## What Gets Installed
+- **Node.js**: ≥18.0.0
+- **Claude Code**: Latest version
+- **Disk Space**: ~15 MB
+- **OS**: macOS, Linux, Windows (with bash/WSL)
 
-### Skills (6.5 MB total)
+## Upgrading
 
-```
-~/.claude/skills/
-├── mozaic-vue-builder/       (~1.3 MB)
-├── mozaic-react-builder/     (~1.4 MB)
-├── mozaic-design-tokens/     (~1.2 MB)
-├── mozaic-css-utilities/     (~1.5 MB)
-└── mozaic-icons/            (~1.1 MB)
+### Upgrade Skills
+
+To upgrade to the latest version:
+
+```bash
+# Uninstall old version
+npx mozaic-mcp-server uninstall-skills
+
+# Clear npm cache (optional)
+npx clear-npx-cache
+
+# Install new version
+npx mozaic-mcp-server install-skills
 ```
 
-### MCP Server (varies by method)
+### Upgrade MCP Server
 
-- **npx**: ~50 MB (downloaded on first run, cached)
-- **Local**: ~150 MB (includes node_modules, source, database)
-- **Global**: ~50 MB (npm global packages)
+MCP server updates automatically when you restart Claude Desktop (it uses the latest npx version).
 
-## Requirements
+## Manual Installation
 
-- **Node.js**: ≥25.0.0
-- **Claude Code**: Latest version
-- **Disk Space**: ~60 MB for complete setup
+### Manual Skills Installation
 
-## Architecture
+If you prefer manual installation:
 
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/merzoukemansouri/adeo-mozaic-mcp.git
+   cd adeo-mozaic-mcp
+   ```
+
+2. Install dependencies and build:
+   ```bash
+   pnpm install
+   pnpm compile
+   ```
+
+3. Run the installer:
+   ```bash
+   node bin/install-skills.js install-skills
+   ```
+
+Alternatively, copy files manually:
+
+```bash
+# Copy skills
+cp -r skills/* ~/.claude/skills/
+
+# Copy database
+cp data/mozaic.db ~/.claude/mozaic.db
+
+# Make scripts executable
+find ~/.claude/skills/mozaic-*/scripts -name "*.sh" -exec chmod +x {} \;
 ```
-┌─────────────────────────────────────────┐
-│           Claude Code                    │
-├─────────────────────────────────────────┤
-│  Skills (Workflows)                      │
-│  ├─ mozaic-vue-builder                  │
-│  ├─ mozaic-react-builder                │
-│  ├─ mozaic-design-tokens                │
-│  ├─ mozaic-css-utilities                │
-│  └─ mozaic-icons                        │
-│                                          │
-│  Uses ↓                                  │
-│                                          │
-│  MCP Server (Data Access)               │
-│  ├─ 11 Tools                            │
-│  └─ SQLite Database (586 tokens,        │
-│     52 Vue components, 39 React         │
-│     components, 1473 icons, etc.)       │
-└─────────────────────────────────────────┘
-```
+
+### Manual MCP Server Installation
+
+1. Follow steps 1-2 above to build the project
+
+2. Add to `~/.claude/config.json`:
+   ```json
+   {
+     "mcpServers": {
+       "mozaic": {
+         "command": "node",
+         "args": ["/path/to/adeo-mozaic-mcp/dist/index.js"]
+       }
+     }
+   }
+   ```
+
+3. Restart Claude Desktop
 
 ## Next Steps
 
-- Read [SKILLS.md](./SKILLS.md) for skill documentation
-- Read [README.md](./README.md) for MCP server details
+- Read [SKILLS.md](./SKILLS.md) for skill documentation and usage
+- Read [README.md](./README.md) for project overview
 - Try the [Web Playground](https://merzoukemansouri.github.io/adeo-mozaic-mcp/#/playground)
 
 ## Support

package/README.md

@@ -1,6 +1,6 @@
-# Mozaic MCP Server
+# Mozaic Design System Skills for Claude Code
 
-An MCP (Model Context Protocol) server that exposes the **Mozaic Design System** by ADEO to Claude and other AI assistants.
+Self-contained Claude Code skills that provide instant access to the **Mozaic Design System** by ADEO. No MCP server configuration required!
 
 **[View Documentation](https://merzoukemansouri.github.io/adeo-mozaic-mcp/)** | **[Try the Playground](https://merzoukemansouri.github.io/adeo-mozaic-mcp/#/playground)**
 
@@ -8,66 +8,74 @@ An MCP (Model Context Protocol) server that exposes the **Mozaic Design System**
 
 ## What It Does
 
-This server indexes the entire Mozaic Design System and makes it queryable through MCP tools. AI assistants can:
+Five interactive skills that help you work with the Mozaic Design System directly in Claude Code. Each skill queries a local SQLite database to provide:
 
-- Look up design tokens (colors, spacing, typography, etc.)
-- Get component documentation with props, slots, events, and examples
-- Search and retrieve icons with SVG/React/Vue code
-- Search documentation pages
-- Generate component code snippets
+- Design tokens (colors, spacing, typography, etc.)
+- Component documentation with props, slots, events, and examples
+- Icon search with SVG/React/Vue code
+- CSS utility classes and layout systems
+- Code generation for Vue 3 and React/TSX
 
-## Claude Code Skills
+## Available Skills
 
-In addition to the MCP server, this repository includes **5 Claude Code skills** that provide interactive, guided workflows for working with Mozaic:
+This package includes **5 self-contained Claude Code skills** with interactive, guided workflows:
 
 - **`mozaic-vue-builder`** - Interactive Vue 3 component generator
-- **`mozaic-react-builder`** - Interactive React/TSX component generator
-- **`mozaic-design-tokens`** - Design tokens and styling expert
-- **`mozaic-css-utilities`** - CSS utilities and layout systems expert
-- **`mozaic-icons`** - Icon search and integration
+- **`mozaic-react-builder`** - Interactive React/TSX component generator with TypeScript
+- **`mozaic-design-tokens`** - Design tokens and styling expert (JSON, SCSS, CSS, JS formats)
+- **`mozaic-css-utilities`** - CSS utilities and layout systems expert (Flexy, Margin, Padding, etc.)
+- **`mozaic-icons`** - Icon search and integration (1,473 icons, Vue & React)
 
-**Quick Install:**
-```bash
-npx mozaic-mcp-server install
-```
+## Installation
 
-**Complete Setup:**
+**Quick start - Install skills (recommended):**
 ```bash
-# 1. Install skills
-npx mozaic-mcp-server install
-
-# 2. Configure MCP server in Claude Code settings:
-#    Command: npx mozaic-mcp-server
-#    (or point to local installation)
+npx mozaic-mcp-server install-skills
 ```
 
-**Learn more:** [SKILLS.md](./SKILLS.md)
-
-## Quick Start
-
-### MCP Server
+This installs all 5 skills to `~/.claude/skills/` and the database to `~/.claude/mozaic.db`. Skills work immediately in Claude Code - no configuration needed!
 
+**Alternative - Install as MCP server:**
 ```bash
-pnpm install
-pnpm build   # Compiles TypeScript & builds the database
-pnpm start   # Starts the MCP server
+npx mozaic-mcp-server install-mcp
 ```
 
-### Claude Code Skills (Optional)
+This adds the MCP server configuration to Claude Desktop settings. Requires Claude Desktop restart.
 
-**Install with npx** (recommended):
+**View all commands:**
 ```bash
-npx mozaic-mcp-server install     # Install all 5 skills
-npx mozaic-mcp-server uninstall   # Uninstall skills
+npx mozaic-mcp-server install
 ```
 
-**Or use local scripts**:
+**Uninstall:**
 ```bash
-./scripts/install-skills.sh    # Install all 5 skills
-./scripts/uninstall-skills.sh  # Uninstall skills
+# Remove skills
+npx mozaic-mcp-server uninstall-skills
+
+# Remove MCP server config
+npx mozaic-mcp-server uninstall-mcp
 ```
 
-See [SKILLS.md](./SKILLS.md) for detailed skill documentation.
+**Learn more:** [SKILLS.md](./SKILLS.md) | [INSTALLATION.md](./INSTALLATION.md)
+
+## How It Works
+
+This package provides **two ways** to access Mozaic Design System in Claude:
+
+### Skills Mode (Recommended)
+1. **Installation**: `npx mozaic-mcp-server install-skills` copies skills and database to your system
+2. **Database**: Skills query a local SQLite database (`~/.claude/mozaic.db`) containing all Mozaic data
+3. **Shell Scripts**: Each skill uses bash scripts to query the database and return results
+4. **No Server Needed**: Everything runs locally - no MCP server configuration required
+
+### MCP Server Mode
+1. **Installation**: `npx mozaic-mcp-server install-mcp` adds server to Claude Desktop config
+2. **Server**: Runs as MCP server providing 11 tools (see MCP Tools section below)
+3. **Configuration**: Requires Claude Desktop restart after installation
+
+**Database Location:** `~/.claude/mozaic.db` (shared by both modes)
+
+See [SKILLS.md](./SKILLS.md) for detailed skill documentation and usage examples.
 
 ## What's Indexed
 
@@ -85,7 +93,9 @@ Documentation sources:
 - Vue Storybook docs (58 pages) - Getting Started, Usage guides
 - React Storybook docs (3 pages) - Getting Started, Usage guides
 
-## MCP Tools
+## MCP Tools (MCP Server Mode)
+
+Available when using `install-mcp` mode in Claude Desktop:
 
 ### Component Tools
 
@@ -204,25 +214,6 @@ Compare performance and effectiveness of MCP server approach vs native Claude sk
 - [ ] Evaluate context window efficiency
 - [ ] Document trade-offs and recommendations
 
-### Release Process
-
-Steps to publish the MCP server:
-
-- [ ] **npm registry**: Publish to npm
-  - Supports [npm Trusted Publishers](./TRUSTED_PUBLISHERS_SETUP.md) for automated, secure publishing
-  - Manual: `npm publish` or automated via GitHub release
-  - See [PUBLISH.md](./PUBLISH.md) for complete guide
-- [ ] **Smithery**: Submit to [smithery.ai](https://smithery.ai) MCP marketplace
-- [ ] **GitHub release**: Create tagged release with changelog (auto-publishes to npm with Trusted Publishers)
-- [ ] **Claude Desktop config**: Document installation in `claude_desktop_config.json`
-- [ ] **Version strategy**: Define semver policy for database schema changes
-
-**Publishing Features**:
-- ✅ Automated publishing via GitHub Actions
-- ✅ npm Trusted Publishers (OIDC) support
-- ✅ Provenance attestation for supply chain security
-- ✅ Skills automatically included in npm package
-
 ### Future Improvements
 
 - [ ] Incremental database updates (avoid full rebuild)