From b4792df8e04a82b118b97ec7697683c0939e206a Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Thu, 16 Oct 2025 23:10:43 +0900 Subject: [PATCH 1/6] feat: add Claude Code plugin configuration Add Claude Code plugin support with MCP server integration: - Add plugin manifest (.claude-plugin/plugin.json) - Configure HTTP transport MCP server (https://ui.nuxt.com/mcp) - Add SessionStart hook for automatic context loading - Create usage documentation (hooks/NUXTUI.md) - Update README with Claude Code installation instructions Features: - 13 MCP tools for components, documentation, templates, and examples - Automatic tool usage instructions on session start - Live documentation access via remote MCP server - Seamless integration with Claude Code plugin system --- .claude-plugin/plugin.json | 35 ++++++++++++++++++ README.md | 22 +++++++++++ hooks/NUXTUI.md | 75 ++++++++++++++++++++++++++++++++++++++ hooks/context.sh | 14 +++++++ hooks/hooks.json | 17 +++++++++ 5 files changed, 163 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 hooks/NUXTUI.md create mode 100755 hooks/context.sh create mode 100644 hooks/hooks.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000000..a1c7b94fd3 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,35 @@ +{ + "name": "nuxt-ui", + "version": "1.0.0", + "description": "Nuxt UI component library with comprehensive documentation, templates, and examples via MCP server", + "author": { + "name": "Nuxt", + "url": "https://github.com/nuxt" + }, + "homepage": "https://ui.nuxt.com", + "repository": "https://github.com/nuxt/ui", + "license": "MIT", + "keywords": [ + "nuxt-ui", + "vue", + "components", + "tailwindcss", + "documentation", + "mcp", + "ui-library" + ], + "hooks": "./hooks/hooks.json", + "mcpServers": { + "nuxt-ui-remote": { + "command": "claude", + "args": [ + "mcp", + "add", + "--transport", + "http", + "nuxt-ui-remote", + "https://ui.nuxt.com/mcp" + ] + } + } +} diff --git a/README.md b/README.md index 107f794192..54ebb2da11 100644 --- a/README.md +++ b/README.md @@ -117,6 +117,28 @@ app.mount('#app') Learn more in the [installation guide](https://ui.nuxt.com/docs/getting-started/installation/vue). +## Claude Code Plugin + +Install Nuxt UI as a Claude Code plugin to get instant access to component documentation, templates, and examples directly in your AI coding sessions: + +```sh +claude +/plugin marketplace add pleaseai/claude-code-plugins +/plugin install nuxt-ui@pleaseai +``` + +This plugin provides: + +- **13 MCP Tools** for accessing components, documentation, templates, and examples +- **Automatic Context Loading** - Usage instructions load automatically on session start +- **Live Documentation** - Always up-to-date with the latest Nuxt UI v4 documentation +- **Component Search** - Find the right component for your use case +- **Template Access** - Quick access to project templates (Starter, Dashboard, SaaS, etc.) + +The plugin connects to Nuxt UI's MCP server at `https://ui.nuxt.com/mcp` and integrates seamlessly with Claude Code's tool system. No additional configuration required! + +Learn more about the MCP server at [https://ui.nuxt.com/docs/getting-started/ai/mcp](https://ui.nuxt.com/docs/getting-started/ai/mcp). + ## Contribution Thank you for considering contributing to Nuxt UI. Here are a few ways you can get involved: diff --git a/hooks/NUXTUI.md b/hooks/NUXTUI.md new file mode 100644 index 0000000000..a1fefc998a --- /dev/null +++ b/hooks/NUXTUI.md @@ -0,0 +1,75 @@ +# Nuxt UI MCP Tools Usage Instructions + +Always use Nuxt UI MCP tools when working with Nuxt UI components, templates, documentation, or examples. + +## When to Use + +- When the user asks about Nuxt UI components, their props, slots, or events +- When implementing Nuxt UI components in code +- When searching for the right component for a specific use case +- When setting up a new project with Nuxt UI templates +- When looking up Nuxt UI documentation or examples +- When migrating between Nuxt UI versions +- When exploring available composables + +## Available MCP Tools + +### Component Operations +- **mcp__nuxt-ui-remote__list_components**: Lists all available Nuxt UI components with categories +- **mcp__nuxt-ui-remote__get_component**: Gets detailed component documentation (requires componentName in PascalCase) +- **mcp__nuxt-ui-remote__get_component_metadata**: Gets component props, slots, and events metadata +- **mcp__nuxt-ui-remote__search_components_by_category**: Search components by category or text filter + +### Template Management +- **mcp__nuxt-ui-remote__list_templates**: Lists all available project templates (Starter, Landing, Docs, SaaS, Dashboard, Chat, Portfolio, Changelog) +- **mcp__nuxt-ui-remote__get_template**: Gets template details and setup instructions + +### Documentation Access +- **mcp__nuxt-ui-remote__list_documentation_pages**: Lists all documentation pages +- **mcp__nuxt-ui-remote__get_documentation_page**: Gets specific documentation page content (requires path starting with /docs/) +- **mcp__nuxt-ui-remote__list_getting_started_guides**: Lists installation and getting started guides +- **mcp__nuxt-ui-remote__get_migration_guide**: Gets version-specific migration guides (v3 or v4) + +### Examples & Composables +- **mcp__nuxt-ui-remote__list_examples**: Lists all UI examples and code demonstrations +- **mcp__nuxt-ui-remote__get_example**: Gets specific example implementation code +- **mcp__nuxt-ui-remote__list_composables**: Lists all available Nuxt UI composables + +## Usage Examples + +### Finding the Right Component +When user asks "What component should I use for a login form?": +1. Use `mcp__nuxt-ui-remote__search_components_by_category` with search="form" +2. Or use `mcp__nuxt-ui-remote__list_components` to browse all components + +### Implementing a Component +When user asks "How do I use the Button component?": +1. Use `mcp__nuxt-ui-remote__get_component` with componentName="Button" +2. Use `mcp__nuxt-ui-remote__get_component_metadata` with componentName="Button" for props/slots/events + +### Setting Up a Project +When user asks "How do I create a dashboard with Nuxt UI?": +1. Use `mcp__nuxt-ui-remote__list_templates` to see available templates +2. Use `mcp__nuxt-ui-remote__get_template` with templateName="dashboard" + +### Getting Documentation +When user asks "How do I install Nuxt UI?": +1. Use `mcp__nuxt-ui-remote__list_getting_started_guides` +2. Use `mcp__nuxt-ui-remote__get_documentation_page` with path="/docs/getting-started/installation/nuxt" + +## Best Practices + +1. **Always fetch component metadata** before implementing complex components +2. **Use search tools** when the exact component name is unknown +3. **Check examples** for implementation patterns and best practices +4. **Reference templates** when starting new projects +5. **Consult migration guides** when upgrading Nuxt UI versions + +## Component Naming Convention + +- Always use **PascalCase** for component names (e.g., "Button", "Input", "Card") +- Documentation paths use **kebab-case** (e.g., "/docs/components/button") + +## Note + +These tools connect to the live Nuxt UI documentation at https://ui.nuxt.com/mcp and provide up-to-date information about Nuxt UI v4. diff --git a/hooks/context.sh b/hooks/context.sh new file mode 100755 index 0000000000..d3bacce280 --- /dev/null +++ b/hooks/context.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +set -euo pipefail + +CONTEXT_FILE="${CLAUDE_PLUGIN_ROOT}/hooks/NUXTUI.md" + +if [ -f "$CONTEXT_FILE" ]; then + CONTEXT_CONTENT=$(cat "$CONTEXT_FILE") + jq -n --arg context "$CONTEXT_CONTENT" '{ + "hookSpecificOutput": { + "hookEventName": "SessionStart", + "additionalContext": $context + } + }' +fi diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000000..9d17d99323 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,17 @@ +{ + "description": "Load Nuxt UI usage instructions at session start", + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/context.sh", + "timeout": 10 + } + ] + } + ] + } +} From a26fdc5caf39ec2ca55d575784a9209eb8145a02 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Thu, 16 Oct 2025 23:14:03 +0900 Subject: [PATCH 2/6] docs: add Claude Code plugin documentation to MCP guide Move Claude Code plugin documentation from README to official MCP documentation: - Add dedicated "Claude Code Plugin" section in MCP guide - Remove plugin documentation from README (keep it focused on library installation) - Highlight plugin as recommended approach for Claude Code users - Document enhanced features: automatic setup, context loading, zero config - Position plugin section after basic MCP setup for progressive disclosure The plugin section emphasizes the benefits of using the plugin over manual MCP setup: - Automatic MCP server configuration - Auto-loading usage instructions on session start - Enhanced Claude integration with automatic tool discovery --- README.md | 22 ----------------- .../docs/1.getting-started/7.ai/1.mcp.md | 24 +++++++++++++++++++ 2 files changed, 24 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 54ebb2da11..107f794192 100644 --- a/README.md +++ b/README.md @@ -117,28 +117,6 @@ app.mount('#app') Learn more in the [installation guide](https://ui.nuxt.com/docs/getting-started/installation/vue). -## Claude Code Plugin - -Install Nuxt UI as a Claude Code plugin to get instant access to component documentation, templates, and examples directly in your AI coding sessions: - -```sh -claude -/plugin marketplace add pleaseai/claude-code-plugins -/plugin install nuxt-ui@pleaseai -``` - -This plugin provides: - -- **13 MCP Tools** for accessing components, documentation, templates, and examples -- **Automatic Context Loading** - Usage instructions load automatically on session start -- **Live Documentation** - Always up-to-date with the latest Nuxt UI v4 documentation -- **Component Search** - Find the right component for your use case -- **Template Access** - Quick access to project templates (Starter, Dashboard, SaaS, etc.) - -The plugin connects to Nuxt UI's MCP server at `https://ui.nuxt.com/mcp` and integrates seamlessly with Claude Code's tool system. No additional configuration required! - -Learn more about the MCP server at [https://ui.nuxt.com/docs/getting-started/ai/mcp](https://ui.nuxt.com/docs/getting-started/ai/mcp). - ## Contribution Thank you for considering contributing to Nuxt UI. Here are a few ways you can get involved: diff --git a/docs/content/docs/1.getting-started/7.ai/1.mcp.md b/docs/content/docs/1.getting-started/7.ai/1.mcp.md index c6c8438433..a792f6ee8f 100644 --- a/docs/content/docs/1.getting-started/7.ai/1.mcp.md +++ b/docs/content/docs/1.getting-started/7.ai/1.mcp.md @@ -102,6 +102,30 @@ Add the server using the CLI command: claude mcp add --transport http nuxt-ui-remote https://ui.nuxt.com/mcp ``` +#### Claude Code Plugin + +::note{icon="i-lucide-sparkles"} +**Recommended for Claude Code users** - Install Nuxt UI as a Claude Code plugin for automatic setup and enhanced integration. +:: + +Install as a Claude Code plugin for seamless integration: + +```bash +claude +/plugin marketplace add pleaseai/claude-code-plugins +/plugin install nuxt-ui@pleaseai +``` + +This plugin provides enhanced features: + +- **Automatic Setup**: MCP server configured automatically on installation +- **Context Loading**: Usage instructions load automatically on session start +- **13 MCP Tools**: Access to all components, documentation, templates, and examples +- **Auto-Discovery**: Claude automatically knows when to use Nuxt UI tools +- **Zero Configuration**: No manual MCP server setup required + +The plugin wraps the Nuxt UI MCP server with automatic context loading, making it easier for Claude to assist with Nuxt UI development without manual configuration. + ### Cursor #### Quick Install From 05830c541dc7ea0586c33857bd85c59de5efd317 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Fri, 17 Oct 2025 03:47:47 +0900 Subject: [PATCH 3/6] feat: add migrate-to-v4 command and reorganize plugin structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive /migrate-to-v4 slash command for v4 migration - Move commands and hooks to .claude-plugin/ directory for better isolation - Update plugin.json to reference new paths - Update MCP server config to use HTTP transport type The migrate-to-v4 command provides phased migration workflow: - Auto-detection of migration path (Nuxt UI Pro/v3 to v4) - Dependency and configuration updates - Component renames (ButtonGroup→FieldGroup, etc.) - Model modifier updates (nullify→nullable) - Nested form updates with new props - Import path migrations - Optional AI SDK v5 migration - Comprehensive verification steps Organizing plugin files under .claude-plugin/ keeps Claude Code plugin functionality separate from the main Nuxt UI repository. --- .claude-plugin/commands/migrate-to-v4.md | 498 +++++++++++++++++++++ {hooks => .claude-plugin/hooks}/NUXTUI.md | 0 {hooks => .claude-plugin/hooks}/context.sh | 0 {hooks => .claude-plugin/hooks}/hooks.json | 0 .claude-plugin/plugin.json | 14 +- 5 files changed, 502 insertions(+), 10 deletions(-) create mode 100644 .claude-plugin/commands/migrate-to-v4.md rename {hooks => .claude-plugin/hooks}/NUXTUI.md (100%) rename {hooks => .claude-plugin/hooks}/context.sh (100%) rename {hooks => .claude-plugin/hooks}/hooks.json (100%) diff --git a/.claude-plugin/commands/migrate-to-v4.md b/.claude-plugin/commands/migrate-to-v4.md new file mode 100644 index 0000000000..63b06e6d32 --- /dev/null +++ b/.claude-plugin/commands/migrate-to-v4.md @@ -0,0 +1,498 @@ +--- +description: Migrate your Nuxt application from Nuxt UI v3 or Nuxt UI Pro to Nuxt UI v4 +--- + +You are assisting with migrating a Nuxt application to Nuxt UI v4. Nuxt UI v4 marks a major milestone where Nuxt UI and Nuxt UI Pro are now unified into a single, fully open-source and free library with 100+ production-ready components. + +**IMPORTANT**: Nuxt UI v4 requires **Nuxt 4**. Ensure the project is on Nuxt 4 before proceeding. + +## Phase 0: Initial Assessment + +First, analyze the current project setup: + +1. Check if the project uses Nuxt UI Pro or Nuxt UI v3: + - Read `package.json` to detect `@nuxt/ui-pro` or `@nuxt/ui` dependencies + - Read `nuxt.config.ts` (or `vite.config.ts` for Vue projects) to confirm module configuration + - Check `app.config.ts` (or `vite.config.ts` for Vue) for `uiPro` configuration + +2. Verify git status and ask the user: + - Whether to create a new migration branch or work on current branch + - If new branch, suggest name like `feat/migrate-nuxt-ui-v4` + +3. Check for AI SDK usage (optional migration): + - Search for imports from `@ai-sdk/vue` or `ai` packages + - Search for chat components: `ChatMessage`, `ChatMessages`, `ChatPrompt`, etc. + +4. Present a summary to the user: + ``` + **Migration Assessment** + - Current version: [Nuxt UI Pro / Nuxt UI v3] + - Nuxt version: [version] + - Framework: [Nuxt / Vue] + - AI SDK components detected: [Yes/No] + - Recommended branch: [branch-name] + + Ready to proceed? + ``` + +Wait for user approval before continuing. + +## Phase 1: Dependency Updates + +Based on the detected setup, perform the appropriate dependency updates: + +### If migrating from Nuxt UI Pro: + +1. Remove `@nuxt/ui-pro` and install `@nuxt/ui`: + ```bash + # Detect package manager (npm, pnpm, yarn, bun) + bun remove @nuxt/ui-pro + bun add @nuxt/ui + ``` + +2. Update module configuration: + - **For Nuxt projects**: Update `nuxt.config.ts` + ```diff + export default defineNuxtConfig({ + modules: [ + - '@nuxt/ui-pro', + + '@nuxt/ui' + ] + }) + ``` + + - **For Vue projects**: Update `vite.config.ts` + ```diff + import { defineConfig } from 'vite' + import vue from '@vitejs/plugin-vue' + - import uiPro from '@nuxt/ui-pro/vite' + + import ui from '@nuxt/ui/vite' + + export default defineConfig({ + plugins: [ + vue(), + - uiPro({ + + ui({ + ui: { + colors: { + primary: 'green', + neutral: 'slate' + } + } + }) + ] + }) + ``` + +### If migrating from Nuxt UI v3: + +1. Update to latest version: + ```bash + bun add @nuxt/ui + ``` + +2. No module configuration changes needed (already using `@nuxt/ui`) + +### Phase 1 Completion: + +After dependency updates: +- Run `bun install` to ensure clean install +- Commit changes: `git commit -m "chore: update to Nuxt UI v4 dependencies"` + +Wait for user approval before continuing to Phase 2. + +## Phase 2: Configuration Updates + +### 2.1 Update App Configuration + +- **For Nuxt projects**: Update `app.config.ts` + ```diff + export default defineAppConfig({ + ui: { + colors: { + primary: 'green', + neutral: 'slate' + }, + + pageCard: { + + slots: { + + root: 'rounded-xl', + + } + + } + }, + - uiPro: { + - pageCard: { + - slots: { + - root: 'rounded-xl', + - } + - } + - } + }) + ``` + +- **For Vue projects**: Update `vite.config.ts` (move `uiPro` config to `ui`) + ```diff + export default defineConfig({ + plugins: [ + vue(), + ui({ + ui: { + colors: { + primary: 'green', + neutral: 'slate' + }, + + pageCard: { + + slots: { + + root: 'rounded-xl', + + } + + } + }, + - uiPro: { + - pageCard: { + - slots: { + - root: 'rounded-xl', + - } + - } + - } + }) + ] + }) + ``` + +### 2.2 Update CSS Imports + +Find CSS files (commonly `app/assets/css/main.css` or `src/assets/css/main.css`) and update: + +```diff +@import "tailwindcss"; +- @import "@nuxt/ui-pro"; ++ @import "@nuxt/ui"; +``` + +**For Nuxt 4 projects upgrading simultaneously**: Update `@source` directive if present: +```diff +@import "tailwindcss"; +@import "@nuxt/ui"; + +- @source "../../content/**/*"; ++ @source "../../../content/**/*"; +``` + +### Phase 2 Completion: + +After configuration updates: +- Run `npx nuxi typecheck` (or `npx vue-tsc` for Vue) to check for issues +- Commit changes: `git commit -m "chore: migrate configuration to Nuxt UI v4"` + +Wait for user approval before continuing to Phase 3. + +## Phase 3: Code Migration + +This phase updates component usage and imports throughout the codebase. + +### 3.1 Rename Components + +Search and replace the following component renames: + +1. **ButtonGroup → FieldGroup**: + ```bash + # Search for UButtonGroup usage + ``` + Replace with: + ```diff + - + + + + + + + - + ``` + +2. **PageMarquee → Marquee**: + ```diff + - + + + ``` + +3. **PageAccordion → Accordion** (with additional props): + ```diff + - + ``` + +### 3.2 Update Model Modifiers + +Search for `v-model.nullify` usage and update: + +```diff +- ++ +``` + +```diff +- ++ +``` + +**Note**: Use `nullable` for `null` values, `optional` for `undefined` values. + +### 3.3 Update Form Components + +Search for nested `UForm` components and update: + +```diff + +``` + +**Key changes**: +- Add `nested` prop to nested forms +- Replace `:state` with `:name` for path-based state access +- Schema transformations now only apply to `@submit` data + +### 3.4 Update Imports + +Search for all imports from `@nuxt/ui-pro` and update: + +```diff +- import type { BannerProps } from '@nuxt/ui-pro' ++ import type { BannerProps } from '@nuxt/ui' +``` + +```diff +- import { findPageHeadline } from '@nuxt/ui-pro/utils/content' ++ import { findPageHeadline } from '@nuxt/content/utils' +``` + +```diff +- import { findPageBreadcrumb } from '@nuxt/ui-pro/utils/content' ++ import { findPageBreadcrumb } from '@nuxt/content/utils' +``` + +### Phase 3 Completion: + +After code migrations: +- Run `npx nuxi typecheck` to verify no type errors +- Run `npm run build` to test build +- Commit changes: `git commit -m "refactor: migrate components and imports to Nuxt UI v4"` + +Wait for user approval before continuing to Phase 4 (if AI SDK detected). + +## Phase 4: AI SDK v5 Migration (Optional) + +**Only perform this phase if AI SDK usage was detected in Phase 0.** + +Ask user: "AI SDK components were detected. Would you like to migrate to AI SDK v5? (Yes/No)" + +If Yes: + +### 4.1 Update AI SDK Dependencies + +```diff +{ + "dependencies": { +- "@ai-sdk/vue": "^1.2.x", ++ "@ai-sdk/vue": "^2.0.x", +- "ai": "^4.3.x" ++ "ai": "^5.0.x" + } +} +``` + +### 4.2 Update Chat Composables + +Replace `useChat` with new `Chat` class: + +```diff + +``` + +### 4.3 Update Message Structure + +Messages now use `parts` instead of `content`: + +```diff +// When manually creating messages +- setMessages([{ ++ messages.push({ + id: '1', + role: 'user', +- content: 'Hello world' ++ parts: [{ type: 'text', text: 'Hello world' }] +- }]) ++ }) +``` + +```diff +// In templates +- ++ +``` + +### 4.4 Update Method Names + +```diff +// Regenerate the last message +- reload() ++ chat.regenerate() + +// Access chat state +- :messages="messages" +- :status="status" ++ :messages="chat.messages" ++ :status="chat.status" +``` + +### 4.5 Add Text Extraction Utility + +For MDC rendering with AI SDK v5: + +```vue + + + +``` + +### Phase 4 Completion: + +After AI SDK migration: +- Run `npx nuxi typecheck` to verify no type errors +- Run tests if available +- Commit changes: `git commit -m "feat: migrate to AI SDK v5"` + +## Phase 5: Final Verification + +Perform comprehensive checks: + +1. **Type checking**: + ```bash + npx nuxi typecheck # For Nuxt + npx vue-tsc # For Vue + ``` + +2. **Build verification**: + ```bash + npm run build + ``` + +3. **Run tests** (if available): + ```bash + npm run test + ``` + +4. **Lint check** (if configured): + ```bash + npm run lint + ``` + +5. **Development server**: + ```bash + npm run dev + ``` + Ask user to verify the application runs correctly. + +### Final Summary + +Present a complete migration summary: + +``` +✅ Nuxt UI v4 Migration Complete + +**Changes Applied:** +- ✅ Dependencies updated to @nuxt/ui v4 +- ✅ Configuration migrated (nuxt.config.ts/vite.config.ts, app.config.ts) +- ✅ CSS imports updated +- ✅ Components renamed (ButtonGroup→FieldGroup, PageMarquee→Marquee, PageAccordion→Accordion) +- ✅ Model modifiers updated (nullify→nullable) +- ✅ Form components updated with nested prop +- ✅ Imports updated from @nuxt/ui-pro to @nuxt/ui +- [✅/➖] AI SDK v5 migration completed (if applicable) + +**Verification Results:** +- Type checking: [✅/❌] +- Build: [✅/❌] +- Tests: [✅/❌] +- Lint: [✅/❌] + +**Next Steps:** +1. Review the changes in git diff +2. Test your application thoroughly +3. Update any custom components that depend on changed APIs +4. Refer to the migration guide for additional edge cases: https://ui.nuxt.com/docs/getting-started/migration/v4 + +**References:** +- Nuxt UI v4 Migration Guide: https://ui.nuxt.com/docs/getting-started/migration/v4 +- AI SDK v5 Migration Guide: https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0 +- Nuxt UI v4 Upgrade PR: https://github.com/nuxt/ui/pull/4698 +``` + +Ask the user if they want to: +1. Push the changes to remote +2. Create a pull request +3. Make any additional adjustments + +## Error Handling + +Throughout the migration, if any step fails: + +1. **Show the error clearly** to the user +2. **Explain what went wrong** and potential causes +3. **Suggest fixes** or ask for user input +4. **Don't proceed** to the next phase until the current issue is resolved +5. **Offer to rollback** to the last successful git commit if needed + +## Important Notes + +- **Backup**: Ensure the user has committed or backed up their work before starting +- **Incremental**: Each phase should be committed separately for easy rollback +- **Testing**: Encourage testing after each major phase +- **Documentation**: Point users to official migration guides for edge cases +- **Breaking Changes**: Explain each breaking change clearly before applying +- **User Control**: Always wait for user approval before proceeding to the next phase diff --git a/hooks/NUXTUI.md b/.claude-plugin/hooks/NUXTUI.md similarity index 100% rename from hooks/NUXTUI.md rename to .claude-plugin/hooks/NUXTUI.md diff --git a/hooks/context.sh b/.claude-plugin/hooks/context.sh similarity index 100% rename from hooks/context.sh rename to .claude-plugin/hooks/context.sh diff --git a/hooks/hooks.json b/.claude-plugin/hooks/hooks.json similarity index 100% rename from hooks/hooks.json rename to .claude-plugin/hooks/hooks.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a1c7b94fd3..02cde86d8c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -18,18 +18,12 @@ "mcp", "ui-library" ], - "hooks": "./hooks/hooks.json", + "commands": "./.claude-plugin/commands/", + "hooks": "./.claude-plugin/hooks/hooks.json", "mcpServers": { "nuxt-ui-remote": { - "command": "claude", - "args": [ - "mcp", - "add", - "--transport", - "http", - "nuxt-ui-remote", - "https://ui.nuxt.com/mcp" - ] + "type": "http", + "url": "https://ui.nuxt.com/mcp" } } } From 96f50ad1bcd10c937fedb2a2defe9d277b53f193 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Fri, 17 Oct 2025 05:32:49 +0900 Subject: [PATCH 4/6] docs: update plugin marketplace and installation commands in MCP guide - Change plugin marketplace and installation commands to use `nuxt/nuxt` and `nuxt-ui@nuxt` respectively for clarity and consistency. --- docs/content/docs/1.getting-started/7.ai/1.mcp.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/docs/1.getting-started/7.ai/1.mcp.md b/docs/content/docs/1.getting-started/7.ai/1.mcp.md index a792f6ee8f..abc817acf7 100644 --- a/docs/content/docs/1.getting-started/7.ai/1.mcp.md +++ b/docs/content/docs/1.getting-started/7.ai/1.mcp.md @@ -112,8 +112,8 @@ Install as a Claude Code plugin for seamless integration: ```bash claude -/plugin marketplace add pleaseai/claude-code-plugins -/plugin install nuxt-ui@pleaseai +/plugin marketplace add nuxt/nuxt +/plugin install nuxt-ui@nuxt ``` This plugin provides enhanced features: From 63cde19f5491bf1c8de0206e38474e96b834c853 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Fri, 17 Oct 2025 05:58:34 +0900 Subject: [PATCH 5/6] refactor: remove Nuxt UI plugin hooks and associated context files - Remove SessionStart hook and related scripts (`context.sh`, `hooks.json`, `NUXTUI.md`) - Update plugin.json to exclude hooks configuration This change streamlines the plugin by removing automatic context loading and usage instructions at session start, aligning with updated plugin requirements. --- .claude-plugin/hooks/NUXTUI.md | 75 --------------------------------- .claude-plugin/hooks/context.sh | 14 ------ .claude-plugin/hooks/hooks.json | 17 -------- .claude-plugin/plugin.json | 1 - 4 files changed, 107 deletions(-) delete mode 100644 .claude-plugin/hooks/NUXTUI.md delete mode 100755 .claude-plugin/hooks/context.sh delete mode 100644 .claude-plugin/hooks/hooks.json diff --git a/.claude-plugin/hooks/NUXTUI.md b/.claude-plugin/hooks/NUXTUI.md deleted file mode 100644 index a1fefc998a..0000000000 --- a/.claude-plugin/hooks/NUXTUI.md +++ /dev/null @@ -1,75 +0,0 @@ -# Nuxt UI MCP Tools Usage Instructions - -Always use Nuxt UI MCP tools when working with Nuxt UI components, templates, documentation, or examples. - -## When to Use - -- When the user asks about Nuxt UI components, their props, slots, or events -- When implementing Nuxt UI components in code -- When searching for the right component for a specific use case -- When setting up a new project with Nuxt UI templates -- When looking up Nuxt UI documentation or examples -- When migrating between Nuxt UI versions -- When exploring available composables - -## Available MCP Tools - -### Component Operations -- **mcp__nuxt-ui-remote__list_components**: Lists all available Nuxt UI components with categories -- **mcp__nuxt-ui-remote__get_component**: Gets detailed component documentation (requires componentName in PascalCase) -- **mcp__nuxt-ui-remote__get_component_metadata**: Gets component props, slots, and events metadata -- **mcp__nuxt-ui-remote__search_components_by_category**: Search components by category or text filter - -### Template Management -- **mcp__nuxt-ui-remote__list_templates**: Lists all available project templates (Starter, Landing, Docs, SaaS, Dashboard, Chat, Portfolio, Changelog) -- **mcp__nuxt-ui-remote__get_template**: Gets template details and setup instructions - -### Documentation Access -- **mcp__nuxt-ui-remote__list_documentation_pages**: Lists all documentation pages -- **mcp__nuxt-ui-remote__get_documentation_page**: Gets specific documentation page content (requires path starting with /docs/) -- **mcp__nuxt-ui-remote__list_getting_started_guides**: Lists installation and getting started guides -- **mcp__nuxt-ui-remote__get_migration_guide**: Gets version-specific migration guides (v3 or v4) - -### Examples & Composables -- **mcp__nuxt-ui-remote__list_examples**: Lists all UI examples and code demonstrations -- **mcp__nuxt-ui-remote__get_example**: Gets specific example implementation code -- **mcp__nuxt-ui-remote__list_composables**: Lists all available Nuxt UI composables - -## Usage Examples - -### Finding the Right Component -When user asks "What component should I use for a login form?": -1. Use `mcp__nuxt-ui-remote__search_components_by_category` with search="form" -2. Or use `mcp__nuxt-ui-remote__list_components` to browse all components - -### Implementing a Component -When user asks "How do I use the Button component?": -1. Use `mcp__nuxt-ui-remote__get_component` with componentName="Button" -2. Use `mcp__nuxt-ui-remote__get_component_metadata` with componentName="Button" for props/slots/events - -### Setting Up a Project -When user asks "How do I create a dashboard with Nuxt UI?": -1. Use `mcp__nuxt-ui-remote__list_templates` to see available templates -2. Use `mcp__nuxt-ui-remote__get_template` with templateName="dashboard" - -### Getting Documentation -When user asks "How do I install Nuxt UI?": -1. Use `mcp__nuxt-ui-remote__list_getting_started_guides` -2. Use `mcp__nuxt-ui-remote__get_documentation_page` with path="/docs/getting-started/installation/nuxt" - -## Best Practices - -1. **Always fetch component metadata** before implementing complex components -2. **Use search tools** when the exact component name is unknown -3. **Check examples** for implementation patterns and best practices -4. **Reference templates** when starting new projects -5. **Consult migration guides** when upgrading Nuxt UI versions - -## Component Naming Convention - -- Always use **PascalCase** for component names (e.g., "Button", "Input", "Card") -- Documentation paths use **kebab-case** (e.g., "/docs/components/button") - -## Note - -These tools connect to the live Nuxt UI documentation at https://ui.nuxt.com/mcp and provide up-to-date information about Nuxt UI v4. diff --git a/.claude-plugin/hooks/context.sh b/.claude-plugin/hooks/context.sh deleted file mode 100755 index d3bacce280..0000000000 --- a/.claude-plugin/hooks/context.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -CONTEXT_FILE="${CLAUDE_PLUGIN_ROOT}/hooks/NUXTUI.md" - -if [ -f "$CONTEXT_FILE" ]; then - CONTEXT_CONTENT=$(cat "$CONTEXT_FILE") - jq -n --arg context "$CONTEXT_CONTENT" '{ - "hookSpecificOutput": { - "hookEventName": "SessionStart", - "additionalContext": $context - } - }' -fi diff --git a/.claude-plugin/hooks/hooks.json b/.claude-plugin/hooks/hooks.json deleted file mode 100644 index 9d17d99323..0000000000 --- a/.claude-plugin/hooks/hooks.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "description": "Load Nuxt UI usage instructions at session start", - "hooks": { - "SessionStart": [ - { - "matcher": "startup", - "hooks": [ - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/context.sh", - "timeout": 10 - } - ] - } - ] - } -} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 02cde86d8c..7dc1937ac0 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -19,7 +19,6 @@ "ui-library" ], "commands": "./.claude-plugin/commands/", - "hooks": "./.claude-plugin/hooks/hooks.json", "mcpServers": { "nuxt-ui-remote": { "type": "http", From d812b8714ca736bcedc9e23ea0884d93cc66080b Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Fri, 17 Oct 2025 06:01:34 +0900 Subject: [PATCH 6/6] docs: add SKILL.md for Nuxt UI component development with MCP tools - Document workflows, tools, and commands for implementing Nuxt UI v4 components - Provide quick references for components, templates, and documentation setup - Outline naming conventions, tool categories, and example scenarios for user requests --- skills/nuxt-ui-mcp/SKILL.md | 83 +++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 skills/nuxt-ui-mcp/SKILL.md diff --git a/skills/nuxt-ui-mcp/SKILL.md b/skills/nuxt-ui-mcp/SKILL.md new file mode 100644 index 0000000000..8cfe8ae3e6 --- /dev/null +++ b/skills/nuxt-ui-mcp/SKILL.md @@ -0,0 +1,83 @@ +--- +name: Working with Nuxt UI Components +description: Implements Nuxt UI components using MCP tools that provide component documentation, props, slots, events, templates, and examples. Use when implementing Nuxt UI components, setting up Nuxt UI projects, searching for Vue components, or when user mentions Nuxt UI, nuxt-ui, UI components, Nuxt templates, or component APIs. +--- + +# Nuxt UI Component Development + +Access Nuxt UI v4 documentation via MCP tools for components, templates, and examples. + +## Quick Reference + +**Component Lookup** +- Unknown component → `search_components_by_category(search="keyword")` +- Known component → `get_component(componentName="Button")` +- Need props/slots → `get_component_metadata(componentName="Button")` + +**Project Setup** +- Browse templates → `list_templates()` +- Get template details → `get_template(templateName="dashboard")` + +**Documentation** +- Installation → `get_documentation_page(path="/docs/getting-started/installation/nuxt")` +- Migration → `get_migration_guide(version="v4")` + +## Component Workflows + +### 1. Find Component by Purpose +``` +User request: "component for login form" +→ search_components_by_category(search="form") +→ get_component_metadata for selected component +→ Implement with correct props +``` + +### 2. Implement Known Component +``` +User request: "add Button with icon" +→ get_component_metadata(componentName="Button") +→ Verify icon prop/slot exists +→ Implement using metadata +``` + +### 3. Setup Project Template +``` +User request: "create SaaS landing page" +→ list_templates() to verify "saas" exists +→ get_template(templateName="saas") +→ Follow setup instructions from template +``` + +## Tool Categories + +### Component Tools +- `list_components`: All components with categories +- `search_components_by_category`: Search by keyword or category +- `get_component`: Full documentation (PascalCase required) +- `get_component_metadata`: Props, slots, events schema + +### Template Tools +- `list_templates`: Available project templates +- `get_template`: Setup instructions for template + +### Documentation Tools +- `list_documentation_pages`: All available docs +- `get_documentation_page`: Specific page (path: /docs/...) +- `list_getting_started_guides`: Installation guides +- `get_migration_guide`: Version migration (v3 or v4) + +### Example & Composable Tools +- `list_examples`: All code examples +- `get_example`: Specific example code +- `list_composables`: Available Nuxt UI composables + +## Naming Rules + +- Components: PascalCase (Button, Input, Card) +- Docs paths: kebab-case (/docs/components/button) +- Templates: lowercase (dashboard, starter, saas) + +## Data Source + +All MCP tools prefix: `mcp__nuxt-ui-remote__` +Documentation source: https://ui.nuxt.com/mcp (Nuxt UI v4) \ No newline at end of file