feat: add Claude Code plugin support with MCP integration

[amondnet]

🔗 Linked issue

N/A - This is a new feature addition that adds Claude Code plugin support to Nuxt UI. Discussion: Adding Claude Code plugin support to improve AI-assisted development experience with Nuxt UI.

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This PR adds Claude Code plugin support for Nuxt UI, enabling seamless integration with Claude Code's plugin system and automatic MCP server configuration.

What's New

Plugin Configuration:

• Add .claude-plugin/plugin.json manifest with MCP server configuration
• Configure HTTP transport to existing MCP server at https://ui.nuxt.com/mcp
• Enable access to all 13 MCP tools (components, documentation, templates, examples)

Automatic Context Loading:

• Add SessionStart hook (hooks/hooks.json) for automatic initialization
• Create context loading script (hooks/context.sh)
• Provide comprehensive usage documentation (hooks/NUXTUI.md) with tool descriptions and examples

Documentation Updates:

• Add dedicated "Claude Code Plugin" section to MCP guide
• Position plugin installation as recommended approach for Claude Code users
• Document enhanced features: automatic setup, context loading, zero configuration

Benefits

For Claude Code Users:

• ✅ Zero configuration required
• ✅ Automatic MCP server setup on plugin installation
• ✅ Usage instructions load automatically on session start
• ✅ Enhanced Claude integration with automatic tool discovery
• ✅ Seamless access to all 13 MCP tools without manual setup

For Nuxt UI:

• ✅ Improved developer experience for Claude Code users
• ✅ Increased discoverability through Claude Code plugin marketplace
• ✅ Better integration with AI-assisted development workflows
• ✅ No changes to existing MCP server infrastructure

Installation

Users can install the plugin with:

claude
/plugin marketplace add pleaseai/claude-code-plugins
/plugin install nuxt-ui@pleaseai

Technical Details

• Plugin Type: Claude Code plugin with HTTP MCP transport
• MCP Server: Uses existing https://ui.nuxt.com/mcp (no server changes)
• Auto-Loading: SessionStart hook loads usage instructions automatically
• Components: 4 new files, 1 documentation update

Files Added/Modified

• .claude-plugin/plugin.json (new) - Plugin manifest
• hooks/hooks.json (new) - SessionStart hook configuration
• hooks/context.sh (new) - Context loading script
• hooks/NUXTUI.md (new) - Usage instructions and tool documentation
• docs/content/docs/1.getting-started/7.ai/1.mcp.md (modified) - Added plugin section

Testing

• ✅ Plugin structure follows Claude Code plugin standards
• ✅ MCP server connection verified through HTTP transport
• ✅ SessionStart hook tested for automatic context loading
• ✅ Documentation renders correctly in Nuxt UI docs
• ✅ All 13 MCP tools accessible through plugin

References

• Claude Code plugin documentation: https://docs.anthropic.com/en/docs/claude-code/plugins
• MCP specification: https://modelcontextprotocol.io/
• Plugin marketplace: https://github.com/pleaseai/claude-code-plugins

📝 Checklist

• I have linked an issue or discussion (N/A - new feature addition)
• I have updated the documentation accordingly (added plugin section to MCP guide)

[pkg-pr-new]

npm i https://pkg.pr.new/@nuxt/ui@5247

commit: d812b87

[HugoRCD]

@amondnet I can't see what really changes between using the plugin or just connecting the MCP server, the only thing I see is that you add instructions via a .MD file but couldn't that be done in an AGENTS.MD file or something? 🤔

And if we adopt this approach, we'll have to publish the plugin under an official name /plugin install nuxt-ui@nuxt, for example

[amondnet]

@HugoRCD You're right that the current Nuxt UI plugin implementation primarily uses the SessionStart hook to load instructions. However, Claude Code plugins provide four major capabilities beyond just MCP servers that can significantly enhance the developer experience:

1. Slash Commands (commands/)
   Plugins can add custom slash commands that appear in Claude's command palette:

   Potential for Nuxt UI:

   /nuxt-ui:scaffold-form - Generate a complete form with validation
   /nuxt-ui:migrate-to-v4 - Guide migration from v3 to v4
   /nuxt-ui:component-gallery - Browse and insert components interactively
   /nuxt-ui:theme-setup - Configure color schemes and design tokens

https://github.com/nuxt/ui/blob/05830c541dc7ea0586c33857bd85c59de5efd317/.claude-plugin/commands/migrate-to-v4.md

2. Subagents (agents/) & Skills (skills/)

   Claude Code plugins support two distinct capabilities for extending Claude's behavior:

   1. Subagents (agents/)

      Subagents are specialized AI assistants with their own context windows and expertise:

      • Independent AI personalities: Each runs with its own system prompt and context
      • Task delegation: Claude delegates specific tasks to the appropriate subagent
      • Tool restrictions: Can limit which tools each subagent can access
      • Isolated context: Prevents context pollution from main conversation
      • Reusable across projects: Available everywhere once created

      Potential for Nuxt UI:

      ---
      name: NuxtUIFormBuilder
      description: Expert at building accessible, validated forms with Nuxt UI
      tools: ["write", "edit"]  # Can use file editing tools
      ---
      
      # Nuxt UI Form Builder Subagent
      
      You are a specialist in creating production-ready forms using Nuxt UI components.
      
      ## When to activate:
      - User requests form creation
      - Form validation needs to be implemented
      - Complex form states need management
      
      ## Your expertise:
      - UForm, UInput, USelect, UCheckbox components
      - Form validation with Zod/Yup
      - Error handling and loading states
      - Accessibility patterns (ARIA labels, etc.)
      
      ## Approach:
      Generate complete, tested form implementations that follow Nuxt UI best practices.

      Real-world benefit: When a user says "Create a user registration form," Claude automatically delegates this task to the Nuxt UI Form Builder subagent, which has specialized knowledge and is isolated from other concerns.

3. Distribution & Updates
   With Plugin:

   claude
   /plugin marketplace add nuxt/nuxt
   /plugin install nuxt-ui@nuxt // agents, mcp, commands, skills
   /plugin install nuxt@nuxt // agents, commands
   /plugin install content@nuxt // agents, commands

   Without Plugin:

   # Each developer must manually:
   1. Find the MCP server documentation
   2. Copy the server URL
   4. Run: claude mcp add --transport http nuxt-ui-remote https://ui.nuxt.com/mcp
   5. Create AGENTS.md file and remember to reference it
   6. Set up any custom hooks manually
   7. Document all of this for team members
   8. Manually check for updates

   Benefits:

   • Single command installation
   • Automatic updates via marketplace
   • Version control and dependency management
   • Team-wide standardization
   • Discoverable via marketplace search

   Plugins can be added any marketplace, making them easy for organizations to manage.

   /plugin install nuxt-ui@org-standards // mcp
   /plugin install postgres@org-standards // mcp
   /plugin install firebaes@org-standards // mcp, commands, agents
   /plugin install tdd@org-standards
   

Real-world example from our company:

We manage internal tools via a company marketplace. New developers run:

/plugin marketplace add our-company/engineering-tools
/plugin install nuxt-ui@our-company // external plgin
/plugin install firebase@our-company // external plugin
/plugin install standards@our-company // commands, agents

All tools auto-update when we push changes. No manual setup docs needed.

For Nuxt: If you create a nuxt/nuxt (or nuxt/marketplace) repository, users can:

/plugin marketplace add nuxt/nuxt
/plugin install nuxt-ui@nuxt

This gives Nuxt full control over distribution while users benefit from automatic updates across all Nuxt tooling (nuxt-ui, devtools, etc.).

[amondnet]

@HugoRCD I've updated it to use the agent skill. Since it loads into the context when the Nuxt UI component is needed, it's highly efficient and convenient.