@hanzo/ui 4.5.0 → 4.5.3

package/MCP-INSTRUCTIONS.md

@@ -0,0 +1,73 @@
+# Using @hanzo/ui with AI Assistants
+
+This guide explains how to use @hanzo/ui with AI assistants through the Model Context Protocol (MCP).
+
+## Getting Started
+
+1. Install the package:
+
+```bash
+npm install @hanzo/ui
+```
+
+2. Start the MCP server:
+
+```bash
+npx @hanzo/ui registry:mcp
+```
+
+3. Configure your AI assistant to use the server.
+
+## Available Commands
+
+- **Initialize a new project**:
+  ```bash
+  npx @hanzo/ui init --style=default
+  ```
+
+- **List available components**:
+  ```bash
+  npx @hanzo/ui list
+  ```
+
+- **Add a component**:
+  ```bash
+  npx @hanzo/ui add button
+  ```
+
+## Using with LLMs
+
+AI Assistants like Claude or ChatGPT can help you explore and use the components. Just describe what you need, and the AI can guide you through:
+
+- Finding the right component
+- Installing and configuring it
+- Using it in your project
+
+Example prompt: "I need a dropdown menu component for my React project. Can you help me find and set it up using @hanzo/ui?"
+
+## Registry Configuration
+
+You can create a custom registry for your components, making them available through the same interface. To create a registry:
+
+1. Set up the registry structure
+2. Run the update-registry script
+3. Host the registry files
+4. Point to your custom registry:
+
+```bash
+npx @hanzo/ui registry:mcp --registry=https://your-registry-url.com/registry.json
+```
+
+## HTTP Mode
+
+For web-based applications, you can run the MCP server in HTTP mode:
+
+```bash
+npx @hanzo/ui registry:mcp --http --port=3333
+```
+
+This exposes an HTTP endpoint at http://localhost:3333 that you can use to communicate with the MCP server.
+
+## Learn More
+
+For detailed documentation, see [README-MCP.md](./README-MCP.md) or visit the [Hanzo UI website](https://ui.hanzo.ai).

package/README-MCP.md

@@ -0,0 +1,175 @@
+# Hanzo UI with MCP Support
+
+This implementation provides Model Context Protocol (MCP) support for the Hanzo UI library, enabling AI assistants to interact with the component registry based on shadcn/ui.
+
+## Quick Start
+
+```bash
+# Run with npx (recommended)
+npx @hanzo/ui registry:mcp
+
+# Or set a custom registry URL
+npx @hanzo/ui registry:mcp --registry=https://ui.hanzo.ai/registry/registry.json
+
+# Run in HTTP mode instead of stdio
+npx @hanzo/ui registry:mcp --http --port=3333
+```
+
+## Setup and Usage
+
+### Configure Your LLM Tool
+
+To configure your AI assistant or LLM to use the Hanzo UI MCP server, add the following configuration:
+
+```json
+{
+  "name": "hanzo-ui",
+  "command": "npx @hanzo/ui registry:mcp"
+}
+```
+
+### Available Tools
+
+The MCP server provides the following tools for AI assistants:
+
+1. `init` - Initialize a new project using @hanzo/ui components and styles
+2. `list_components` - List all available components in the registry
+3. `get_component` - Get detailed information about a specific component
+4. `add_component` - Get instructions for adding a component to a project
+5. `list_styles` - List all available styles in the registry
+6. `search_registry` - Search the registry for components matching criteria
+
+### Registry Configuration
+
+The registry URL can be configured by setting the `REGISTRY_URL` environment variable:
+
+```bash
+export REGISTRY_URL="https://ui.hanzo.ai/registry/registry.json"
+npx @hanzo/ui registry:mcp
+```
+
+Or by using the `--registry` command-line option:
+
+```bash
+npx @hanzo/ui registry:mcp --registry=https://ui.hanzo.ai/registry/registry.json
+```
+
+## HTTP Mode
+
+You can run the MCP server in HTTP mode, which exposes the server over HTTP rather than stdio:
+
+```bash
+npx @hanzo/ui registry:mcp --http --port=3333
+```
+
+This allows you to access the MCP server directly from web applications or other HTTP clients.
+
+## Developer Instructions
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/hanzoai/ui.git
+cd ui/pkg/ui
+
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run the MCP server
+node ./bin/cli.js registry:mcp
+```
+
+### Project Structure
+
+- `/pkg/ui/mcp/`: MCP server implementation
+- `/pkg/ui/registry/`: Registry schema and API
+- `/pkg/ui/bin/`: CLI tools for running the MCP server
+
+### Creating a Registry
+
+The registry is compatible with shadcn/ui's registry format. To create a custom registry:
+
+1. Create a `registry.json` file using the schema from `/pkg/ui/registry/schema.ts`
+2. Build the registry using a build script
+3. Host the registry files on a web server or CDN
+4. Point the MCP server to your custom registry using the `--registry` option
+
+## How It Works
+
+The MCP server enables AI assistants to:
+
+1. Discover and browse available components in your registry
+2. Fetch detailed information about specific components
+3. Provide instructions on adding components to projects
+4. Initialize new projects with your component library
+
+This makes it easy for users to interact with your UI library through conversational interfaces.
+
+## Example Interactions
+
+### Initialize a Project
+
+```
+Assistant: To create a new project with Hanzo UI components, you can run:
+
+npx create-next-app@latest my-app
+cd my-app
+npx @hanzo/ui@latest init
+```
+
+### Add a Component
+
+```
+Assistant: To add the Button component to your project:
+
+npx @hanzo/ui@latest add button
+
+This will install the component and its dependencies.
+```
+
+### Search for Components
+
+```
+Assistant: I found several form-related components:
+- form
+- input
+- checkbox
+- select
+- textarea
+
+Which one would you like to add to your project?
+```
+
+## Technical Details
+
+### Registry Schema
+
+The registry schema is compatible with shadcn/ui and includes:
+
+- Component metadata (name, description, type)
+- Dependencies (npm packages)
+- Registry dependencies (other components)
+- Component files with source code
+- Category and subcategory information
+
+### MCP Integration
+
+The MCP server implements the Model Context Protocol, enabling AI assistants to:
+
+- Query the registry for components
+- Get detailed information about components
+- Provide installation instructions
+- Generate example usage code
+
+### Command-Line Interface
+
+The CLI provides options for:
+
+- Setting the registry URL
+- Running in HTTP mode
+- Specifying the port for HTTP mode
+- Verbose logging

package/bin/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+/**
+ * Main CLI entry point for @hanzo/ui
+ * Supports various commands including registry:mcp
+ */
+
+const { program } = require("commander");
+
+// Define the version from the package.json
+let version = "4.5.0";
+try {
+  const packageJson = require("../package.json");
+  version = packageJson.version || version;
+} catch (error) {
+  // Use default version if package.json can't be loaded
+}
+
+// Set up the program
+program
+  .name("@hanzo/ui")
+  .description("Hanzo UI Component Library CLI")
+  .version(version);
+  
+// Add the MCP command (main command)
+program
+  .command("mcp")
+  .description("Start the Hanzo UI MCP server for AI assistants")
+  .option(
+    "-r, --registry <url>", 
+    "URL to the registry.json file",
+    process.env.REGISTRY_URL || "https://ui.hanzo.ai/registry/registry.json"
+  )
+  .option(
+    "-p, --port <port>",
+    "Port to listen on (for HTTP mode)",
+    "3333"
+  )
+  .option(
+    "--http",
+    "Run in HTTP mode instead of stdio mode",
+    false
+  )
+  .action(async (options) => {
+    // Delegate to the dedicated MCP binary
+    require("./mcp.js");
+  });
+
+// Add the registry:mcp command (alias for compatibility)
+program
+  .command("registry:mcp")
+  .description("Starts the registry MCP server (alias for 'mcp')")
+  .option(
+    "-r, --registry <url>", 
+    "URL to the registry.json file",
+    process.env.REGISTRY_URL
+  )
+  .option(
+    "-p, --port <port>",
+    "Port to listen on (for HTTP mode)",
+    "3333"
+  )
+  .option(
+    "--http",
+    "Run in HTTP mode instead of stdio mode",
+    false
+  )
+  .action(async (options) => {
+    try {
+      // Set environment variables based on options
+      if (options.registry) {
+        process.env.REGISTRY_URL = options.registry;
+      }
+      
+      // Set port if running in HTTP mode
+      if (options.http) {
+        process.env.MCP_HTTP_MODE = "true";
+        process.env.MCP_PORT = options.port;
+      }
+
+      // Show info about the server
+      console.error("Starting Hanzo UI MCP server...");
+      console.error(`Registry URL: ${process.env.REGISTRY_URL || "[Using default registry]"}`);
+      
+      if (options.http) {
+        console.error(`Running in HTTP mode on port ${options.port}`);
+      } else {
+        console.error("Running in stdio mode");
+      }
+      
+      // Load and run the MCP server script
+      require("./registry-mcp.js");
+    } catch (error) {
+      console.error("Error starting MCP server:", error);
+      process.exit(1);
+    }
+  });
+
+// Parse command line arguments
+program.parse();

package/bin/create-registry.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+/**
+ * Simple registry builder for @hanzo/ui
+ * Creates the necessary structure for the MCP registry
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Configuration
+const REGISTRY_DIR = path.resolve(__dirname, '../registry');
+const PUBLIC_DIR = path.resolve(__dirname, '../public');
+const OUTPUT_FILE = path.resolve(__dirname, '../registry.json');
+const REGISTRY_STYLES = ['default', 'new-york']; 
+
+// Registry schema
+const registrySchema = {
+  "$schema": "https://ui.shadcn.com/schema/registry.json",
+  "name": "hanzo",
+  "homepage": "https://ui.hanzo.ai",
+  "items": []
+};
+
+// Create the basic registry structure
+function createRegistry() {
+  console.log('Creating registry structure...');
+  
+  const items = [];
+  
+  // Ensure registry directory exists
+  if (!fs.existsSync(REGISTRY_DIR)) {
+    fs.mkdirSync(REGISTRY_DIR, { recursive: true });
+  }
+  
+  // Create style directories and add them to registry items
+  for (const style of REGISTRY_STYLES) {
+    const styleDir = path.join(REGISTRY_DIR, style);
+    if (!fs.existsSync(styleDir)) {
+      fs.mkdirSync(styleDir, { recursive: true });
+      
+      // Create ui and block directories
+      fs.mkdirSync(path.join(styleDir, 'ui'), { recursive: true });
+      fs.mkdirSync(path.join(styleDir, 'block'), { recursive: true });
+    }
+    
+    // Add style to registry
+    items.push({
+      name: style,
+      type: 'registry:style',
+      description: `The ${style} style for Hanzo UI components.`,
+      files: []
+    });
+  }
+  
+  // Add primitive components as empty placeholders
+  const primitives = [
+    'accordion', 'alert', 'avatar', 'badge', 'button', 'card', 
+    'checkbox', 'dialog', 'input', 'label', 'popover', 'select', 
+    'table', 'tabs', 'toast'
+  ];
+  
+  for (const component of primitives) {
+    items.push({
+      name: component,
+      type: 'registry:component',
+      description: `A ${component} component for your UI.`,
+      files: [
+        {
+          path: `default/ui/${component}/${component}.tsx`,
+          type: 'registry:component'
+        }
+      ]
+    });
+  }
+  
+  // Update registry.json
+  registrySchema.items = items;
+  
+  // Create output directory if it doesn't exist
+  const outputDir = path.dirname(OUTPUT_FILE);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  
+  // Write registry.json
+  fs.writeFileSync(OUTPUT_FILE, JSON.stringify(registrySchema, null, 2), 'utf8');
+  console.log(`Registry updated with ${items.length} items.`);
+  
+  // Create public/r directory if it doesn't exist
+  const publicRDir = path.join(PUBLIC_DIR, 'r');
+  if (!fs.existsSync(publicRDir)) {
+    fs.mkdirSync(publicRDir, { recursive: true });
+  }
+  
+  // Generate individual component JSON files
+  console.log('Generating individual component JSON files...');
+  for (const item of items) {
+    const componentFile = path.join(publicRDir, `${item.name}.json`);
+    fs.writeFileSync(componentFile, JSON.stringify(item, null, 2), 'utf8');
+  }
+  
+  console.log(`Generated ${items.length} component JSON files.`);
+  console.log('Registry creation complete!');
+}
+
+// Run the registry creation
+createRegistry();