astro-component-kit 0.4.1 → 0.5.0

package/README.md

@@ -13,6 +13,7 @@
 
 ## ✨ Features
 
+- 🤖 **Official MCP Server & AI development** — connect Cursor, Claude, Codex, Lovable, or any MCP client (`https://mcp.astrocomponents.dev/sse` or `npx astro-component-kit mcp install <client>`)
 - 🛍️ **Multi-page production templates** — 3 complete templates (E-commerce Store, Editorial Boutique, SaaS Hotel) with state management, cart persistence, and live previews
 - 🎨 **Dark & Light theme** — dark mode first with official `[data-theme="light"]` support, adaptive tokens, and glassmorphism
 - ⚡ **Full-page sections** — 41+ production-ready landing sections (Heroes, Bento Grids, Pricing Matrices, Testimonials, CTAs, FAQs, Teams, Footers)
@@ -106,6 +107,39 @@ Open [http://localhost:4321](http://localhost:4321) to browse components locally
 
 ---
 
+## 🤖 Build with AI via MCP (Model Context Protocol)
+
+Astro Components Kit provides an official **Model Context Protocol (MCP)** server. Connect it to **Cursor, Claude Desktop, Windsurf, or Antigravity** so your AI assistant can discover components, check TypeScript props, and generate production Astro code directly in your project.
+
+### Remote SSE Connection (Recommended — Zero install)
+
+Add this endpoint to your editor's MCP settings (`claude_desktop_config.json`, Cursor Settings -> Features -> MCP, etc.):
+
+```json
+{
+  "mcpServers": {
+    "astro-components": {
+      "url": "https://mcp.astrocomponents.dev/sse"
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `search_components` | Search by keyword, category, or tag (e.g. `"buy box"`, `"kpi chart"`, `"pricing"`) |
+| `get_component` | Detailed component metadata, TypeScript `Props`, import statements, and usage code |
+| `get_component_code` | Raw `.astro` source code ready to inject into your project |
+| `list_categories` | Overview of all 13 component categories with item counts |
+| `list_templates` | Overview of the 3 multi-page production templates (Nova Store, Forma Studio, The Lobby) |
+| `get_template` | Complete template architecture, pages, store configuration, and routing guide |
+| `get_design_tokens` | CSS tokens, color variables, spacing scale, and dark/light theme setup |
+| `get_library_info` | High-level overview, active version, total counts, and quickstart guide |
+
+---
+
 ## 📚 Component & Section Library
 
 **320+ components & full-page sections** across 13 categories plus 3 complete templates:
@@ -241,7 +275,7 @@ import { MinimalFooterGrid } from 'astro-component-kit/layout';
 
 <!-- 2. Hero Header -->
 <HeroGradient 
-  badge="New Release v0.4.1"
+  badge="New Release v0.5.0"
   title="Build Production Websites at Lightning Speed"
   subtitle="Zero client JavaScript runtime, accessible UI, and modern dark glassmorphism."
 />

package/bin/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// bin/cli.js
+// Direct CLI runner for astro-component-kit.
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installMcpForClient } from './installer.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.resolve(__dirname, '..');
+
+const args = process.argv.slice(2);
+const first = args[0]?.toLowerCase();
+
+async function main() {
+  // 1. Fast-path: 1-click install command runs natively in pure Node.js
+  if (first === 'install' || (first === 'mcp' && args[1]?.toLowerCase() === 'install')) {
+    const client = first === 'install' ? args[1] : args[2];
+    if (!client) {
+      console.log(`\n🚀 Astro Components Kit — 1-Click MCP Installer\n`);
+      console.log(`Usage:`);
+      console.log(`  npx astro-component-kit mcp install <cursor|claude|codex|lovable|mcp>\n`);
+      console.log(`Example:`);
+      console.log(`  npx astro-component-kit mcp install cursor\n`);
+      process.exit(1);
+    }
+
+    const success = await installMcpForClient(client);
+    process.exit(success ? 0 : 1);
+  }
+
+  // 2. Help command
+  if (!first || first === 'help' || first === '--help' || first === '-h') {
+    console.log(`
+🚀 Astro Components Kit (astro-component-kit)
+
+Usage:
+  npx astro-component-kit mcp install <cursor|claude|codex|lovable|mcp>
+    → Automatically configure your AI editor/agent to connect to the MCP server
+
+  npx astro-component-kit mcp serve
+    → Start local HTTP/SSE MCP server (default port 3000)
+
+  npx astro-component-kit mcp --stdio
+    → Run in stdio mode for local MCP integrations
+
+Remote SSE Endpoint:
+  https://mcp.astrocomponents.dev/sse
+`);
+    process.exit(0);
+  }
+
+  // 3. For serve / stdio modes, invoke MCP runner
+  const tsxPath = path.resolve(rootDir, 'node_modules/.bin/tsx');
+  const mcpEntry = path.resolve(rootDir, 'src/mcp/index.ts');
+  const proc = spawn(process.execPath, [tsxPath, mcpEntry, ...args], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+  proc.on('exit', (code) => process.exit(code || 0));
+}
+
+main().catch((err) => {
+  console.error('[cli] Error:', err);
+  process.exit(1);
+});

package/bin/installer.js

@@ -0,0 +1,179 @@
+// bin/installer.js
+// Pure Node.js automated 1-click CLI installer with zero dependencies.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const MCP_SERVER_URL = 'https://mcp.astrocomponents.dev/sse';
+
+const SERVER_CONFIG = {
+  url: MCP_SERVER_URL,
+};
+
+function getHomeDir() {
+  return os.homedir();
+}
+
+export function normalizeClient(input) {
+  if (!input || typeof input !== 'string') return null;
+  const c = input.toLowerCase().trim();
+  if (c === 'cursor' || c === 'cursos') return 'cursor';
+  if (c === 'claude' || c === 'claude-desktop' || c === 'claude-code') return 'claude';
+  if (c === 'codex' || c === 'openai-codex' || c === 'copilot') return 'codex';
+  if (c === 'lovable' || c === 'lovable-dev') return 'lovable';
+  if (c === 'mcp' || c === 'universal' || c === 'generic') return 'mcp';
+  if (c === 'windsurf') return 'windsurf';
+  if (c === 'cline') return 'cline';
+  return null;
+}
+
+/**
+ * Returns the candidate configuration paths for each supported client.
+ */
+function getClientConfigPaths(client) {
+  const home = getHomeDir();
+  const platform = os.platform();
+
+  switch (client) {
+    case 'cursor': {
+      const localCursor = path.resolve(process.cwd(), '.cursor/mcp.json');
+      const globalCursor = path.resolve(home, '.cursor/mcp.json');
+      return { primary: localCursor, fallback: globalCursor };
+    }
+    case 'claude': {
+      if (platform === 'darwin') {
+        return { primary: path.resolve(home, 'Library/Application Support/Claude/claude_desktop_config.json') };
+      }
+      if (platform === 'win32') {
+        const appData = process.env.APPDATA || path.resolve(home, 'AppData/Roaming');
+        return { primary: path.resolve(appData, 'Claude/claude_desktop_config.json') };
+      }
+      return { primary: path.resolve(home, '.config/Claude/claude_desktop_config.json') };
+    }
+    case 'codex': {
+      const localCodex = path.resolve(process.cwd(), '.codex/mcp.json');
+      const globalCodex = path.resolve(home, '.codex/config.json');
+      return { primary: localCodex, fallback: globalCodex };
+    }
+    case 'lovable': {
+      const localLovable = path.resolve(process.cwd(), '.lovable/mcp.json');
+      const globalLovable = path.resolve(home, '.lovable/config.json');
+      return { primary: localLovable, fallback: globalLovable };
+    }
+    case 'mcp': {
+      const localMcp = path.resolve(process.cwd(), 'mcp.json');
+      const globalMcp = path.resolve(home, '.mcp/config.json');
+      return { primary: localMcp, fallback: globalMcp };
+    }
+    case 'windsurf': {
+      return { primary: path.resolve(home, '.codeium/windsurf/mcp_config.json') };
+    }
+    case 'cline': {
+      if (platform === 'darwin') {
+        return {
+          primary: path.resolve(
+            home,
+            'Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json'
+          ),
+        };
+      }
+      if (platform === 'win32') {
+        const appData = process.env.APPDATA || path.resolve(home, 'AppData/Roaming');
+        return {
+          primary: path.resolve(
+            appData,
+            'Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json'
+          ),
+        };
+      }
+      return {
+        primary: path.resolve(
+          home,
+          '.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json'
+        ),
+      };
+    }
+    default:
+      return { primary: path.resolve(process.cwd(), 'mcp.json') };
+  }
+}
+
+/**
+ * Installs or updates the astro-components MCP server in the target client's configuration.
+ */
+export async function installMcpForClient(targetClient) {
+  const client = normalizeClient(targetClient);
+  const validClients = ['cursor', 'claude', 'codex', 'lovable', 'mcp', 'windsurf', 'cline'];
+
+  if (!client) {
+    console.error(`\n❌ Unknown client "${targetClient}".`);
+    console.log(`   Supported clients: ${validClients.join(', ')}`);
+    console.log(`\nExamples:`);
+    console.log(`   npx astro-component-kit mcp install cursor`);
+    console.log(`   npx astro-component-kit mcp install claude`);
+    console.log(`   npx astro-component-kit mcp install codex`);
+    console.log(`   npx astro-component-kit mcp install lovable`);
+    console.log(`   npx astro-component-kit mcp install mcp\n`);
+    return false;
+  }
+
+  const { primary } = getClientConfigPaths(client);
+  const targetDir = path.dirname(primary);
+
+  console.log(`\n📦 Configuring Astro Components Kit MCP for [${client}]...`);
+  console.log(`   Target config: ${primary}`);
+
+  try {
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+
+    let config = {};
+    if (fs.existsSync(primary)) {
+      try {
+        const raw = fs.readFileSync(primary, 'utf8');
+        config = JSON.parse(raw);
+      } catch {
+        config = {};
+      }
+    }
+
+    if (!config || typeof config !== 'object') {
+      config = {};
+    }
+
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+      config.mcpServers = {};
+    }
+
+    // Add or update astro-components server
+    config.mcpServers['astro-components'] = SERVER_CONFIG;
+
+    fs.writeFileSync(primary, JSON.stringify(config, null, 2) + '\n', 'utf8');
+
+    console.log(`\n✅ Successfully installed!`);
+    console.log(`   Server name: "astro-components"`);
+    console.log(`   Endpoint:    ${MCP_SERVER_URL}`);
+    console.log(`\n💡 What to do next:`);
+    console.log(`   Restart ${client.toUpperCase()} (or reload MCP servers), then prompt your AI:`);
+    console.log(`   > "Search astro-components for ecommerce cards and buy box"`);
+    console.log(`   > "Insert a KPI stat tile chart from astro-components"\n`);
+    return true;
+  } catch (err) {
+    console.error(`\n❌ Failed to write configuration: ${err?.message || err}`);
+    console.log(`\nYou can configure it manually by adding this JSON:`);
+    console.log(
+      JSON.stringify(
+        {
+          mcpServers: {
+            'astro-components': SERVER_CONFIG,
+          },
+        },
+        null,
+        2
+      )
+    );
+    return false;
+  }
+}
+

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "astro-component-kit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "A free, open-source accessible UI component library for Astro",
   "type": "module",
   "main": "./src/components/index.ts",
   "module": "./src/components/index.ts",
   "types": "./src/components/types.d.ts",
+  "bin": {
+    "astro-component-kit": "./bin/cli.js"
+  },
   "exports": {
     ".": "./src/components/index.ts",
     "./buttons": "./src/components/lib/buttons/index.ts",
@@ -27,10 +30,13 @@
     "./global.css": "./src/styles/global.css"
   },
   "files": [
+    "bin/",
     "src/components/lib/",
     "src/components/index.ts",
     "src/components/types.d.ts",
     "src/styles/global.css",
+    "src/mcp/",
+    "src/data/registry/",
     "LICENSE",
     "README.md"
   ],
@@ -40,10 +46,13 @@
     "build": "astro build",
     "preview": "astro preview",
     "astro": "astro",
-    "typecheck": "astro check",
+    "typecheck": "ASTRO_TELEMETRY_DISABLED=1 astro check",
     "registry:generate": "node scripts/generate-registry.mjs",
-    "prepublishOnly": "astro check",
-    "indexnow:dry": "node scripts/indexnow.mjs --dry-run"
+    "prepublishOnly": "ASTRO_TELEMETRY_DISABLED=1 astro check",
+    "indexnow:dry": "node scripts/indexnow.mjs --dry-run",
+    "mcp:start": "tsx src/mcp/index.ts",
+    "mcp:dev": "tsx watch src/mcp/index.ts",
+    "mcp:stdio": "tsx src/mcp/index.ts --stdio"
   },
   "keywords": [
     "astro",
@@ -93,10 +102,18 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@astrojs/sitemap": "^3.7.2"
+    "@astrojs/sitemap": "^3.7.2",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "cors": "^2.8.6",
+    "express": "^5.3.0",
+    "express-rate-limit": "^8.7.3",
+    "tsx": "^4.23.15",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
     "@types/three": "^0.184.0",
     "apexcharts": "^3.45.1",
     "astro": ">=5.0.0",

package/src/components/lib/sections/ChangelogSection.astro

@@ -27,6 +27,12 @@ const {
   title = 'Changelog',
   subtitle = 'New components, improvements and fixes, shipped every week.',
   releases = [
+    { version: 'v0.5.0', date: '2026-11-04', title: 'Official MCP Server & 1-Click AI Integrations', changes: [
+      { type: 'new', text: 'Official remote SSE MCP server (mcp.astrocomponents.dev) and local stdio mode.' },
+      { type: 'new', text: '1-click CLI installer (`npx astro-component-kit mcp install <client>`) for Cursor, Claude, Codex, Lovable and universal MCP.' },
+      { type: 'new', text: 'Dedicated 21st.dev-style /mcp interactive landing page with client tabs and tools catalog.' },
+      { type: 'new', text: '8 built-in AI tools with real-time discovery of 340+ components, templates, and design tokens.' },
+    ] },
     { version: 'v0.4.1', date: '2026-11-04', title: 'Multi-page templates & e-commerce suite', changes: [
       { type: 'new', text: 'Three complete production templates: Nova Store, Forma Studio & The Lobby.' },
       { type: 'new', text: '17 e-commerce components with persistent cart, filters and checkout.' },

package/src/data/registry/app.ts

@@ -0,0 +1,93 @@
+// src/data/registry/app.ts
+// App & Dashboard components (SaaS shells, tables, boards, settings). Source via `source()`.
+import type { ComponentDoc } from './types';
+import { source } from './sources';
+
+interface Meta { slug: string; name: string; file: string; description: string; tags: string[]; featured?: boolean; usage: string }
+
+function item(meta: Meta): ComponentDoc {
+  const component = meta.file.replace('.astro', '');
+  return {
+    slug: meta.slug,
+    name: meta.name,
+    description: meta.description,
+    category: 'app',
+    tags: ['app', 'dashboard', 'saas', ...meta.tags],
+    featured: meta.featured ?? false,
+    code: source(`app/${meta.file}`),
+    usage: `---
+import { ${component} } from 'astro-component-kit/app';
+---
+
+${meta.usage.trim()}`,
+    installation: {
+      manual: [
+        'Zero runtime dependencies — server-rendered HTML with a small progressive script.',
+        'Copy app-icons.ts (icons, initials and avatar hues) into src/components/app/.',
+        `Copy ${meta.file} next to it.`,
+        'Set --app-accent (and optionally the light/dark tokens) to match your brand.',
+      ].map((s, i) => `${i + 1}. ${s}`).join('\n'),
+    },
+  };
+}
+
+export const app: ComponentDoc[] = [
+  item({ slug: 'app-sidebar', name: 'App Sidebar', file: 'AppSidebar.astro', featured: true,
+    description: 'SaaS sidebar with workspace switcher, grouped nav with icons and badges, collapsible icon rail and plan card.',
+    tags: ['sidebar', 'navigation', 'shell'],
+    usage: `<AppSidebar currentHref="/app/" groups={[{ items: [{ label: 'Dashboard', href: '/app/', icon: 'dashboard' }, { label: 'Reservations', href: '/app/reservations/', icon: 'calendar', badge: 4 }] }]} />` }),
+  item({ slug: 'app-topbar', name: 'App Topbar', file: 'AppTopbar.astro', featured: true,
+    description: 'App top bar with ⌘K search, notifications dropdown with unread count, theme toggle and user menu.',
+    tags: ['topbar', 'header', 'notifications', 'user-menu'],
+    usage: `<AppTopbar user={{ name: 'Lucía Ortega', role: 'General manager' }} />` }),
+  item({ slug: 'page-header', name: 'Page Header', file: 'PageHeader.astro',
+    description: 'App page heading with breadcrumb, description, period switcher, action buttons and underline tabs.',
+    tags: ['header', 'toolbar', 'tabs'],
+    usage: `<PageHeader title="Reports" periods={['7d', '30d', 'Year']} actions={[{ label: 'Export', icon: 'download' }]} />` }),
+  item({ slug: 'data-table', name: 'Data Table', file: 'DataTable.astro', featured: true,
+    description: 'Client-side table with search, status chips, sortable columns, row selection, bulk bar, pagination and typed cells.',
+    tags: ['table', 'data', 'sort', 'pagination', 'filter'],
+    usage: `<DataTable title="Customers" rows={rows} columns={[
+  { key: 'name', label: 'Name', type: 'person', sortable: true },
+  { key: 'status', label: 'Status', type: 'status' },
+  { key: 'total', label: 'Total', type: 'money', align: 'right', sortable: true },
+]} />` }),
+  item({ slug: 'room-rack', name: 'Room Rack', file: 'RoomRack.astro', featured: true,
+    description: 'Booking timeline (tape chart): rooms by days with status-coloured reservation bars, today marker and detail panel.',
+    tags: ['timeline', 'calendar', 'booking', 'gantt', 'hotel'],
+    usage: `<RoomRack days={['Mon 3', 'Tue 4', 'Wed 5']} rooms={[{ id: '101', name: '101', type: 'Standard' }]} bookings={[{ room: '101', guest: 'Elena', start: 0, nights: 2, status: 'confirmed' }]} />` }),
+  item({ slug: 'housekeeping-board', name: 'Housekeeping Board', file: 'HousekeepingBoard.astro',
+    description: 'Room status board by floor — clean, dirty, inspecting, occupied, out of order — with filters and quick status changes.',
+    tags: ['status', 'board', 'grid', 'hotel', 'operations'],
+    usage: `<HousekeepingBoard rooms={[{ number: '101', floor: 'Floor 1', status: 'dirty', assignee: 'Rosa' }]} />` }),
+  item({ slug: 'arrivals-board', name: 'Arrivals Board', file: 'ArrivalsBoard.astro',
+    description: 'Front-desk list with arrivals, departures and in-house tabs plus one-click check-in / check-out.',
+    tags: ['list', 'tabs', 'check-in', 'hotel'],
+    usage: `<ArrivalsBoard arrivals={[{ guest: 'Elena Duarte', room: '204', time: '14:00', vip: true }]} />` }),
+  item({ slug: 'guest-profile-card', name: 'Guest Profile Card', file: 'GuestProfileCard.astro',
+    description: 'CRM profile with avatar, loyalty tier, contact links, lifetime stats, preferences, upcoming stay and staff notes.',
+    tags: ['profile', 'crm', 'customer', 'card'],
+    usage: `<GuestProfileCard guest={{ name: 'Elena Duarte', email: 'elena@mail.com' }} tier="Gold" />` }),
+  item({ slug: 'settings-section', name: 'Settings Section', file: 'SettingsSection.astro',
+    description: 'Settings block with title and help text beside a fields card with Save / Cancel and a saved confirmation.',
+    tags: ['settings', 'form', 'account'],
+    usage: `<SettingsSection title="Notifications" description="Choose what reaches you.">
+  <SwitchRow name="bookings" label="New bookings" />
+</SettingsSection>` }),
+  item({ slug: 'switch-row', name: 'Switch Row', file: 'SwitchRow.astro',
+    description: 'Settings row with label, description and an accessible on/off switch.',
+    tags: ['switch', 'toggle', 'settings', 'form'],
+    usage: `<SwitchRow name="weekly" label="Weekly report" description="Every Monday at 9:00." checked />` }),
+  item({ slug: 'team-members', name: 'Team Members', file: 'TeamMembers.astro',
+    description: 'Team management with roles, status, invite form and two-step remove.',
+    tags: ['team', 'users', 'roles', 'invite'],
+    usage: `<TeamMembers seats={10} members={[{ name: 'Lucía Ortega', email: 'lucia@hotel.com', role: 'Owner', you: true }]} />` }),
+  item({ slug: 'plan-usage-card', name: 'Plan Usage Card', file: 'PlanUsageCard.astro',
+    description: 'Billing summary with plan, renewal, usage meters with thresholds, payment method and upgrade action.',
+    tags: ['billing', 'plan', 'usage', 'meter'],
+    usage: `<PlanUsageCard plan="Pro" usage={[{ label: 'Rooms', used: 42, limit: 50 }]} />` }),
+  item({ slug: 'auth-card', name: 'Auth Card', file: 'AuthCard.astro', featured: true,
+    description: 'Split-screen sign-in / sign-up with SSO buttons, show-password toggle, validation and a brand panel.',
+    tags: ['auth', 'login', 'sign-in', 'form'],
+    usage: `<AuthCard mode="signin" brand="Lobby" successHref="/app/" />` }),
+];