diff --git a/docs/superpowers/plans/2026-03-29-phase3-mcp-server-cli.md b/docs/superpowers/plans/2026-03-29-phase3-mcp-server-cli.md
new file mode 100644
index 0000000..b257bc7
--- /dev/null
+++ b/docs/superpowers/plans/2026-03-29-phase3-mcp-server-cli.md
@@ -0,0 +1,1374 @@
+# Phase 3: MCP Server + CLI — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build an MCP server that reads Zod schemas and Meta objects from core/ and exposes 5 tools for AI agents (discover, inspect, validate, add, compose), plus a CLI wrapper for humans.
+
+**Architecture:** The MCP server imports component schemas/meta at startup, builds a component registry in memory, and exposes tools via `@modelcontextprotocol/sdk`. Each tool is a separate module. The CLI (`pettyui`) is a thin wrapper that calls the same registry logic without MCP transport.
+
+**Tech Stack:** @modelcontextprotocol/sdk, Zod v4 (with `z.toJsonSchema()`), TypeScript, Vitest, Node.js
+
+**Spec:** `docs/superpowers/specs/2026-03-29-pettyui-ai-first-architecture.md`
+
+**Parallelism:** Tasks 1-2 sequential (foundation). Tasks 3-7 parallel (each tool is independent). Task 8 (CLI) after tools. Task 9 last.
+
+```
+Wave 1 (sequential):  Task 1 (package scaffold)
+                      Task 2 (component registry)
+
+Wave 2 (parallel):    Task 3 (pettyui.discover)
+                      Task 4 (pettyui.inspect)
+                      Task 5 (pettyui.validate)
+                      Task 6 (pettyui.add)
+                      Task 7 (pettyui.compose)
+
+Wave 3 (sequential):  Task 8 (CLI wrapper)
+                      Task 9 (build config + verification)
+```
+
+---
+
+### Task 1: MCP Package Scaffold
+
+**Files:**
+- Create: `packages/mcp/package.json`
+- Create: `packages/mcp/tsconfig.json`
+- Create: `packages/mcp/src/index.ts`
+- Create: `packages/mcp/src/server.ts`
+
+- [ ] **Step 1: Create package.json**
+
+Create `packages/mcp/package.json`:
+
+```json
+{
+  "name": "pettyui-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for PettyUI — AI's interface to the component library",
+  "type": "module",
+  "bin": {
+    "pettyui": "./dist/cli.js",
+    "pettyui-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    },
+    "./registry": {
+      "import": "./dist/registry.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "pettyui": "workspace:*",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}
+```
+
+- [ ] **Step 2: Create tsconfig.json**
+
+Create `packages/mcp/tsconfig.json`:
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "declaration": true,
+    "emitDeclarationMaps": true
+  },
+  "include": ["src"]
+}
+```
+
+- [ ] **Step 3: Create server.ts — MCP server setup**
+
+Create `packages/mcp/src/server.ts`:
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+/** Creates and configures the PettyUI MCP server with all tools registered. */
+export function createPettyUIServer(): McpServer {
+  const server = new McpServer({
+    name: "pettyui",
+    version: "0.1.0",
+  });
+
+  return server;
+}
+```
+
+- [ ] **Step 4: Create index.ts — entry point with stdio transport**
+
+Create `packages/mcp/src/index.ts`:
+
+```typescript
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createPettyUIServer } from "./server.js";
+
+const server = createPettyUIServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+- [ ] **Step 5: Install dependencies**
+
+```bash
+cd packages/mcp && pnpm install
+```
+
+- [ ] **Step 6: Build and verify**
+
+```bash
+cd packages/mcp && pnpm build
+```
+
+Expected: Compiles without errors.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/mcp/
+git commit -m "feat(mcp): scaffold MCP server package with stdio transport"
+```
+
+---
+
+### Task 2: Component Registry
+
+The registry is the brain — it loads all component schemas and meta objects into an in-memory index that the tools query.
+
+**Files:**
+- Create: `packages/mcp/src/registry.ts`
+- Create: `packages/mcp/tests/registry.test.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Create `packages/mcp/tests/registry.test.ts`:
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { ComponentRegistry } from "../src/registry.js";
+
+describe("ComponentRegistry", () => {
+  it("loads all components", () => {
+    const registry = new ComponentRegistry();
+    const components = registry.listComponents();
+    expect(components.length).toBeGreaterThan(30);
+  });
+
+  it("finds component by exact name", () => {
+    const registry = new ComponentRegistry();
+    const dialog = registry.getComponent("Dialog");
+    expect(dialog).toBeDefined();
+    expect(dialog!.meta.name).toBe("Dialog");
+    expect(dialog!.meta.parts).toContain("Content");
+    expect(dialog!.meta.requiredParts).toContain("Title");
+  });
+
+  it("finds component by case-insensitive name", () => {
+    const registry = new ComponentRegistry();
+    const dialog = registry.getComponent("dialog");
+    expect(dialog).toBeDefined();
+    expect(dialog!.meta.name).toBe("Dialog");
+  });
+
+  it("returns undefined for unknown component", () => {
+    const registry = new ComponentRegistry();
+    expect(registry.getComponent("NonExistent")).toBeUndefined();
+  });
+
+  it("searches by description text", () => {
+    const registry = new ComponentRegistry();
+    const results = registry.search("modal overlay");
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].meta.name).toBe("Dialog");
+  });
+
+  it("searches by intent matching", () => {
+    const registry = new ComponentRegistry();
+    const results = registry.search("searchable dropdown");
+    const names = results.map((r) => r.meta.name);
+    expect(names).toContain("Combobox");
+  });
+
+  it("gets JSON schema for a component", () => {
+    const registry = new ComponentRegistry();
+    const dialog = registry.getComponent("Dialog");
+    expect(dialog!.jsonSchemas).toBeDefined();
+    expect(dialog!.jsonSchemas.root).toBeDefined();
+  });
+
+  it("has styled registry info when available", () => {
+    const registry = new ComponentRegistry();
+    const dialog = registry.getComponent("Dialog");
+    expect(dialog!.hasStyledVersion).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cd packages/mcp && pnpm vitest run tests/registry.test.ts
+```
+
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement ComponentRegistry**
+
+Create `packages/mcp/src/registry.ts`:
+
+```typescript
+import { z } from "zod/v4";
+import type { ComponentMeta } from "pettyui/dialog";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** A registered component with schema, meta, and optional styled version info. */
+export interface RegisteredComponent {
+  meta: ComponentMeta;
+  schemas: Record<string, z.ZodType>;
+  jsonSchemas: Record<string, unknown>;
+  hasStyledVersion: boolean;
+  exportPath: string;
+}
+
+/** Search result with relevance score. */
+export interface SearchResult extends RegisteredComponent {
+  score: number;
+}
+
+/** Registry of all PettyUI components — loaded at startup, queried by tools. */
+export class ComponentRegistry {
+  private components = new Map<string, RegisteredComponent>();
+
+  constructor() {
+    this.loadComponents();
+  }
+
+  private loadComponents(): void {
+    const componentImports = this.getComponentImports();
+    for (const entry of componentImports) {
+      this.registerComponent(entry);
+    }
+  }
+
+  private getComponentImports(): Array<{ name: string; mod: Record<string, unknown>; exportPath: string }> {
+    const entries: Array<{ name: string; mod: Record<string, unknown>; exportPath: string }> = [];
+    const componentsDir = this.resolveComponentsDir();
+    if (!componentsDir) return entries;
+
+    const dirs = fs.readdirSync(componentsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    for (const dir of dirs) {
+      const propsFile = path.join(componentsDir, dir, `${dir}.props.ts`);
+      const propsFileAlt = path.join(componentsDir, dir, `${dir}.props.js`);
+      if (!fs.existsSync(propsFile) && !fs.existsSync(propsFileAlt)) continue;
+
+      try {
+        const mod = this.requireComponent(dir);
+        if (mod) {
+          const kebabName = dir;
+          entries.push({ name: kebabName, mod, exportPath: `pettyui/${kebabName}` });
+        }
+      } catch {
+        // Skip components that fail to load
+      }
+    }
+    return entries;
+  }
+
+  private resolveComponentsDir(): string | null {
+    try {
+      const corePkgPath = require.resolve("pettyui/dialog");
+      const coreDir = path.dirname(path.dirname(corePkgPath));
+      const srcDir = path.join(coreDir, "src", "components");
+      if (fs.existsSync(srcDir)) return srcDir;
+      return null;
+    } catch {
+      const fallback = path.resolve(import.meta.dirname, "../../core/src/components");
+      if (fs.existsSync(fallback)) return fallback;
+      return null;
+    }
+  }
+
+  private requireComponent(name: string): Record<string, unknown> | null {
+    try {
+      const componentsDir = this.resolveComponentsDir();
+      if (!componentsDir) return null;
+      const propsPath = path.join(componentsDir, name, `${name}.props.ts`);
+      if (!fs.existsSync(propsPath)) return null;
+      // Dynamic import would be async — for now, we statically register known components
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  private registerComponent(entry: { name: string; mod: Record<string, unknown>; exportPath: string }): void {
+    const meta = this.findMeta(entry.mod);
+    if (!meta) return;
+
+    const schemas = this.findSchemas(entry.mod);
+    const jsonSchemas: Record<string, unknown> = {};
+    for (const [key, schema] of Object.entries(schemas)) {
+      try {
+        jsonSchemas[key] = z.toJsonSchema(schema);
+      } catch {
+        jsonSchemas[key] = { type: "object", description: "Schema conversion failed" };
+      }
+    }
+
+    const hasStyledVersion = this.checkStyledVersion(entry.name);
+
+    this.components.set(meta.name.toLowerCase(), {
+      meta,
+      schemas,
+      jsonSchemas,
+      hasStyledVersion,
+      exportPath: entry.exportPath,
+    });
+  }
+
+  private findMeta(mod: Record<string, unknown>): ComponentMeta | undefined {
+    for (const value of Object.values(mod)) {
+      if (value && typeof value === "object" && "name" in value && "description" in value && "parts" in value && "requiredParts" in value) {
+        return value as ComponentMeta;
+      }
+    }
+    return undefined;
+  }
+
+  private findSchemas(mod: Record<string, unknown>): Record<string, z.ZodType> {
+    const schemas: Record<string, z.ZodType> = {};
+    for (const [key, value] of Object.entries(mod)) {
+      if (key.endsWith("Schema") && value instanceof z.ZodType) {
+        const shortKey = key.replace(/PropsSchema$/, "").replace(/Schema$/, "");
+        schemas[shortKey.charAt(0).toLowerCase() + shortKey.slice(1)] = value;
+      }
+    }
+    return schemas;
+  }
+
+  private checkStyledVersion(kebabName: string): boolean {
+    try {
+      const registryDir = path.resolve(import.meta.dirname, "../../registry/src/components");
+      return fs.existsSync(path.join(registryDir, `${kebabName}.tsx`));
+    } catch {
+      return false;
+    }
+  }
+
+  /** Get all registered components. */
+  listComponents(): RegisteredComponent[] {
+    return Array.from(this.components.values());
+  }
+
+  /** Get a component by name (case-insensitive). */
+  getComponent(name: string): RegisteredComponent | undefined {
+    return this.components.get(name.toLowerCase());
+  }
+
+  /** Search components by intent/description text. Simple word-match scoring. */
+  search(query: string): SearchResult[] {
+    const terms = query.toLowerCase().split(/\s+/);
+    const results: SearchResult[] = [];
+
+    for (const component of this.components.values()) {
+      const searchText = `${component.meta.name} ${component.meta.description}`.toLowerCase();
+      let score = 0;
+      for (const term of terms) {
+        if (searchText.includes(term)) score += 1;
+        if (component.meta.name.toLowerCase() === term) score += 3;
+        if (component.meta.name.toLowerCase().includes(term)) score += 1;
+      }
+      if (score > 0) {
+        results.push({ ...component, score });
+      }
+    }
+
+    return results.sort((a, b) => b.score - a.score);
+  }
+}
+```
+
+**NOTE TO IMPLEMENTER:** The dynamic import approach above won't work directly with TypeScript source files. The actual implementation should use a **static registration approach** — explicitly importing each component's props module at build time. Create a `packages/mcp/src/component-imports.ts` file that does:
+
+```typescript
+import { DialogRootPropsSchema, DialogContentPropsSchema, DialogMeta } from "pettyui/dialog";
+import { ButtonPropsSchema, ButtonMeta } from "pettyui/button";
+// ... all 39 components
+
+export const COMPONENT_REGISTRY = [
+  { exportPath: "pettyui/dialog", meta: DialogMeta, schemas: { dialogRoot: DialogRootPropsSchema, dialogContent: DialogContentPropsSchema } },
+  { exportPath: "pettyui/button", meta: ButtonMeta, schemas: { button: ButtonPropsSchema } },
+  // ... all components
+];
+```
+
+Then `ComponentRegistry` loads from this static list instead of filesystem scanning.
+
+- [ ] **Step 4: Create component-imports.ts with static imports**
+
+Create `packages/mcp/src/component-imports.ts` that statically imports all 39 component schemas and meta objects from `pettyui/*` exports. Use the pattern:
+
+```typescript
+import { DialogRootPropsSchema, DialogContentPropsSchema, DialogMeta } from "pettyui/dialog";
+// ... repeat for all 39 components
+
+export interface ComponentEntry {
+  exportPath: string;
+  meta: ComponentMeta;
+  schemas: Record<string, z.ZodType>;
+}
+
+export const COMPONENT_ENTRIES: ComponentEntry[] = [
+  { exportPath: "pettyui/dialog", meta: DialogMeta, schemas: { dialogRoot: DialogRootPropsSchema, dialogContent: DialogContentPropsSchema } },
+  // ... all 39
+];
+```
+
+Read `packages/core/package.json` exports to get the full list of component names.
+
+- [ ] **Step 5: Update registry to use static imports**
+
+Modify `packages/mcp/src/registry.ts` to load from `COMPONENT_ENTRIES` instead of filesystem scanning.
+
+- [ ] **Step 6: Run tests**
+
+```bash
+cd packages/mcp && pnpm vitest run tests/registry.test.ts
+```
+
+Expected: All 8 tests pass.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/mcp/src/registry.ts packages/mcp/src/component-imports.ts packages/mcp/tests/registry.test.ts
+git commit -m "feat(mcp): add ComponentRegistry with static imports and search"
+```
+
+---
+
+### Task 3: pettyui.discover Tool
+
+**Files:**
+- Create: `packages/mcp/src/tools/discover.ts`
+- Create: `packages/mcp/tests/tools/discover.test.ts`
+- Modify: `packages/mcp/src/server.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Create `packages/mcp/tests/tools/discover.test.ts`:
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { handleDiscover } from "../../src/tools/discover.js";
+import { ComponentRegistry } from "../../src/registry.js";
+
+describe("pettyui.discover", () => {
+  const registry = new ComponentRegistry();
+
+  it("finds components matching intent", async () => {
+    const result = await handleDiscover(registry, { intent: "modal overlay" });
+    expect(result.length).toBeGreaterThan(0);
+    expect(result[0].name).toBe("Dialog");
+  });
+
+  it("returns multiple matches ranked by relevance", async () => {
+    const result = await handleDiscover(registry, { intent: "select option from list" });
+    expect(result.length).toBeGreaterThan(1);
+    const names = result.map((r) => r.name);
+    expect(names).toContain("Select");
+  });
+
+  it("returns empty array for no matches", async () => {
+    const result = await handleDiscover(registry, { intent: "xyznonexistent" });
+    expect(result).toEqual([]);
+  });
+
+  it("limits results to maxResults", async () => {
+    const result = await handleDiscover(registry, { intent: "input", maxResults: 3 });
+    expect(result.length).toBeLessThanOrEqual(3);
+  });
+});
+```
+
+- [ ] **Step 2: Implement discover tool**
+
+Create `packages/mcp/src/tools/discover.ts`:
+
+```typescript
+import type { ComponentRegistry } from "../registry.js";
+
+interface DiscoverInput {
+  intent: string;
+  maxResults?: number;
+}
+
+interface DiscoverResult {
+  name: string;
+  description: string;
+  exportPath: string;
+  parts: readonly string[];
+  hasStyledVersion: boolean;
+  score: number;
+}
+
+/** Handles pettyui.discover — semantic search by intent. */
+export async function handleDiscover(registry: ComponentRegistry, input: DiscoverInput): Promise<DiscoverResult[]> {
+  const maxResults = input.maxResults ?? 10;
+  const results = registry.search(input.intent);
+
+  return results.slice(0, maxResults).map((r) => ({
+    name: r.meta.name,
+    description: r.meta.description,
+    exportPath: r.exportPath,
+    parts: r.meta.parts,
+    hasStyledVersion: r.hasStyledVersion,
+    score: r.score,
+  }));
+}
+```
+
+- [ ] **Step 3: Register tool in server.ts**
+
+Update `packages/mcp/src/server.ts` to register the discover tool:
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
+import { ComponentRegistry } from "./registry.js";
+import { handleDiscover } from "./tools/discover.js";
+
+export function createPettyUIServer(): McpServer {
+  const server = new McpServer({ name: "pettyui", version: "0.1.0" });
+  const registry = new ComponentRegistry();
+
+  server.tool(
+    "pettyui.discover",
+    "Search for components by describing what you need. Returns matching components ranked by relevance.",
+    { intent: z.string().describe("Natural language description of what you need"), maxResults: z.number().optional().describe("Max results to return. Defaults to 10") },
+    async ({ intent, maxResults }) => {
+      const results = await handleDiscover(registry, { intent, maxResults });
+      return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+    },
+  );
+
+  return server;
+}
+```
+
+- [ ] **Step 4: Run tests and commit**
+
+```bash
+cd packages/mcp && pnpm vitest run tests/tools/discover.test.ts
+git add packages/mcp/src/tools/discover.ts packages/mcp/tests/tools/discover.test.ts packages/mcp/src/server.ts
+git commit -m "feat(mcp): add pettyui.discover tool for semantic component search"
+```
+
+---
+
+### Task 4: pettyui.inspect Tool
+
+**Files:**
+- Create: `packages/mcp/src/tools/inspect.ts`
+- Create: `packages/mcp/tests/tools/inspect.test.ts`
+- Modify: `packages/mcp/src/server.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Create `packages/mcp/tests/tools/inspect.test.ts`:
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { handleInspect } from "../../src/tools/inspect.js";
+import { ComponentRegistry } from "../../src/registry.js";
+
+describe("pettyui.inspect", () => {
+  const registry = new ComponentRegistry();
+
+  it("returns full component info", async () => {
+    const result = await handleInspect(registry, { component: "Dialog" });
+    expect(result).toBeDefined();
+    expect(result!.name).toBe("Dialog");
+    expect(result!.description).toBeTruthy();
+    expect(result!.parts.length).toBeGreaterThan(0);
+    expect(result!.requiredParts.length).toBeGreaterThan(0);
+    expect(result!.props).toBeDefined();
+    expect(result!.exportPath).toBe("pettyui/dialog");
+  });
+
+  it("includes JSON schema for props", async () => {
+    const result = await handleInspect(registry, { component: "Dialog" });
+    expect(result!.props.dialogRoot).toBeDefined();
+    expect(result!.props.dialogRoot.type).toBe("object");
+  });
+
+  it("includes minimal example", async () => {
+    const result = await handleInspect(registry, { component: "Dialog" });
+    expect(result!.example).toContain("Dialog");
+  });
+
+  it("returns null for unknown component", async () => {
+    const result = await handleInspect(registry, { component: "FakeComponent" });
+    expect(result).toBeNull();
+  });
+
+  it("is case-insensitive", async () => {
+    const result = await handleInspect(registry, { component: "dialog" });
+    expect(result).toBeDefined();
+    expect(result!.name).toBe("Dialog");
+  });
+});
+```
+
+- [ ] **Step 2: Implement inspect tool**
+
+Create `packages/mcp/src/tools/inspect.ts`:
+
+```typescript
+import type { ComponentRegistry } from "../registry.js";
+
+interface InspectInput {
+  component: string;
+  includeSource?: boolean;
+}
+
+interface InspectResult {
+  name: string;
+  description: string;
+  exportPath: string;
+  parts: readonly string[];
+  requiredParts: readonly string[];
+  props: Record<string, unknown>;
+  hasStyledVersion: boolean;
+  example: string;
+}
+
+/** Generates a minimal valid usage example from component meta. */
+function generateExample(name: string, parts: readonly string[], requiredParts: readonly string[]): string {
+  const lines: string[] = [];
+  lines.push(`import { ${name} } from "pettyui/${toKebab(name)}";`);
+  lines.push("");
+
+  if (requiredParts.includes("Root") || parts.includes("Root")) {
+    lines.push(`<${name}>`);
+    for (const part of requiredParts) {
+      if (part === "Root") continue;
+      lines.push(`  <${name}.${part}>...</${name}.${part}>`);
+    }
+    lines.push(`</${name}>`);
+  } else {
+    lines.push(`<${name} />`);
+  }
+  return lines.join("\n");
+}
+
+/** Converts PascalCase to kebab-case. */
+function toKebab(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/** Handles pettyui.inspect — returns full schema + parts + example for a component. */
+export async function handleInspect(registry: ComponentRegistry, input: InspectInput): Promise<InspectResult | null> {
+  const component = registry.getComponent(input.component);
+  if (!component) return null;
+
+  return {
+    name: component.meta.name,
+    description: component.meta.description,
+    exportPath: component.exportPath,
+    parts: component.meta.parts,
+    requiredParts: component.meta.requiredParts,
+    props: component.jsonSchemas,
+    hasStyledVersion: component.hasStyledVersion,
+    example: generateExample(component.meta.name, component.meta.parts, component.meta.requiredParts),
+  };
+}
+```
+
+- [ ] **Step 3: Register in server.ts and commit**
+
+Add the inspect tool registration to `server.ts`, run tests, commit.
+
+```bash
+cd packages/mcp && pnpm vitest run tests/tools/inspect.test.ts
+git add packages/mcp/src/tools/inspect.ts packages/mcp/tests/tools/inspect.test.ts packages/mcp/src/server.ts
+git commit -m "feat(mcp): add pettyui.inspect tool for component schema inspection"
+```
+
+---
+
+### Task 5: pettyui.validate Tool
+
+**Files:**
+- Create: `packages/mcp/src/tools/validate.ts`
+- Create: `packages/mcp/tests/tools/validate.test.ts`
+- Modify: `packages/mcp/src/server.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Create `packages/mcp/tests/tools/validate.test.ts`:
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { handleValidate } from "../../src/tools/validate.js";
+import { ComponentRegistry } from "../../src/registry.js";
+
+describe("pettyui.validate", () => {
+  const registry = new ComponentRegistry();
+
+  it("validates correct props", async () => {
+    const result = await handleValidate(registry, {
+      component: "Dialog",
+      schema: "dialogRoot",
+      props: { open: true, modal: false },
+    });
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it("rejects invalid props", async () => {
+    const result = await handleValidate(registry, {
+      component: "Dialog",
+      schema: "dialogRoot",
+      props: { open: "yes" },
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  it("validates empty props for optional schemas", async () => {
+    const result = await handleValidate(registry, {
+      component: "Dialog",
+      schema: "dialogRoot",
+      props: {},
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it("checks required parts are present", async () => {
+    const result = await handleValidate(registry, {
+      component: "Dialog",
+      parts: ["Root", "Content"],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain("Missing required part: Title");
+  });
+
+  it("passes when all required parts present", async () => {
+    const result = await handleValidate(registry, {
+      component: "Dialog",
+      parts: ["Root", "Content", "Title"],
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it("returns error for unknown component", async () => {
+    const result = await handleValidate(registry, {
+      component: "FakeComponent",
+      props: {},
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Component "FakeComponent" not found');
+  });
+});
+```
+
+- [ ] **Step 2: Implement validate tool**
+
+Create `packages/mcp/src/tools/validate.ts`:
+
+```typescript
+import type { ComponentRegistry } from "../registry.js";
+
+interface ValidateInput {
+  component: string;
+  schema?: string;
+  props?: Record<string, unknown>;
+  parts?: string[];
+}
+
+interface ValidateResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/** Handles pettyui.validate — validates props against schema and checks required parts. */
+export async function handleValidate(registry: ComponentRegistry, input: ValidateInput): Promise<ValidateResult> {
+  const component = registry.getComponent(input.component);
+  if (!component) {
+    return { valid: false, errors: [`Component "${input.component}" not found`] };
+  }
+
+  const errors: string[] = [];
+
+  if (input.props !== undefined && input.schema) {
+    const schema = component.schemas[input.schema];
+    if (!schema) {
+      errors.push(`Schema "${input.schema}" not found on ${component.meta.name}`);
+    } else {
+      const result = schema.safeParse(input.props);
+      if (!result.success) {
+        for (const issue of result.error.issues) {
+          const path = issue.path.length > 0 ? ` at "${issue.path.join(".")}"` : "";
+          errors.push(`${issue.message}${path}`);
+        }
+      }
+    }
+  }
+
+  if (input.parts !== undefined) {
+    for (const required of component.meta.requiredParts) {
+      if (!input.parts.includes(required)) {
+        errors.push(`Missing required part: ${required}`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+```
+
+- [ ] **Step 3: Register in server.ts and commit**
+
+```bash
+cd packages/mcp && pnpm vitest run tests/tools/validate.test.ts
+git add packages/mcp/src/tools/validate.ts packages/mcp/tests/tools/validate.test.ts packages/mcp/src/server.ts
+git commit -m "feat(mcp): add pettyui.validate tool for props and parts validation"
+```
+
+---
+
+### Task 6: pettyui.add Tool
+
+**Files:**
+- Create: `packages/mcp/src/tools/add.ts`
+- Create: `packages/mcp/tests/tools/add.test.ts`
+- Modify: `packages/mcp/src/server.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Create `packages/mcp/tests/tools/add.test.ts`:
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { handleAdd } from "../../src/tools/add.js";
+import { ComponentRegistry } from "../../src/registry.js";
+
+describe("pettyui.add", () => {
+  const registry = new ComponentRegistry();
+
+  it("returns styled component source for Dialog", async () => {
+    const result = await handleAdd(registry, { component: "Dialog" });
+    expect(result).toBeDefined();
+    expect(result!.files.length).toBeGreaterThan(0);
+    expect(result!.files[0].path).toContain("dialog");
+    expect(result!.files[0].content).toContain("Dialog");
+    expect(result!.dependencies).toContain("pettyui/dialog");
+  });
+
+  it("returns null for component without styled version", async () => {
+    const result = await handleAdd(registry, { component: "Checkbox" });
+    expect(result).toBeNull();
+  });
+
+  it("returns null for unknown component", async () => {
+    const result = await handleAdd(registry, { component: "FakeComponent" });
+    expect(result).toBeNull();
+  });
+
+  it("includes target path", async () => {
+    const result = await handleAdd(registry, { component: "Dialog", targetDir: "src/ui" });
+    expect(result!.files[0].path).toContain("src/ui");
+  });
+});
+```
+
+- [ ] **Step 2: Implement add tool**
+
+Create `packages/mcp/src/tools/add.ts`:
+
+```typescript
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ComponentRegistry } from "../registry.js";
+
+interface AddInput {
+  component: string;
+  targetDir?: string;
+}
+
+interface AddResult {
+  files: Array<{ path: string; content: string }>;
+  dependencies: string[];
+}
+
+/** Resolves the registry components directory. */
+function getRegistryDir(): string {
+  return path.resolve(import.meta.dirname, "../../registry/src/components");
+}
+
+/** Converts PascalCase to kebab-case. */
+function toKebab(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/** Handles pettyui.add — copies styled component from registry. */
+export async function handleAdd(registry: ComponentRegistry, input: AddInput): Promise<AddResult | null> {
+  const component = registry.getComponent(input.component);
+  if (!component || !component.hasStyledVersion) return null;
+
+  const kebabName = toKebab(component.meta.name);
+  const registryDir = getRegistryDir();
+  const sourcePath = path.join(registryDir, `${kebabName}.tsx`);
+
+  if (!fs.existsSync(sourcePath)) return null;
+
+  const content = fs.readFileSync(sourcePath, "utf-8");
+  const targetDir = input.targetDir ?? "src/components/ui";
+  const targetPath = path.join(targetDir, `${kebabName}.tsx`);
+
+  return {
+    files: [{ path: targetPath, content }],
+    dependencies: [component.exportPath],
+  };
+}
+```
+
+- [ ] **Step 3: Register in server.ts and commit**
+
+```bash
+cd packages/mcp && pnpm vitest run tests/tools/add.test.ts
+git add packages/mcp/src/tools/add.ts packages/mcp/tests/tools/add.test.ts packages/mcp/src/server.ts
+git commit -m "feat(mcp): add pettyui.add tool for copying styled components from registry"
+```
+
+---
+
+### Task 7: pettyui.compose Tool
+
+**Files:**
+- Create: `packages/mcp/src/tools/compose.ts`
+- Create: `packages/mcp/tests/tools/compose.test.ts`
+- Modify: `packages/mcp/src/server.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Create `packages/mcp/tests/tools/compose.test.ts`:
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { handleCompose } from "../../src/tools/compose.js";
+import { ComponentRegistry } from "../../src/registry.js";
+
+describe("pettyui.compose", () => {
+  const registry = new ComponentRegistry();
+
+  it("generates composed JSX for specified components", async () => {
+    const result = await handleCompose(registry, {
+      components: ["Dialog", "Button"],
+    });
+    expect(result.jsx).toContain("Dialog");
+    expect(result.jsx).toContain("Button");
+    expect(result.imports).toContain("pettyui/dialog");
+    expect(result.imports).toContain("pettyui/button");
+  });
+
+  it("generates imports for all components", async () => {
+    const result = await handleCompose(registry, {
+      components: ["Form", "TextField", "Button"],
+    });
+    expect(result.imports.length).toBe(3);
+  });
+
+  it("uses required parts in generated JSX", async () => {
+    const result = await handleCompose(registry, {
+      components: ["Dialog"],
+    });
+    expect(result.jsx).toContain("Dialog.Content");
+    expect(result.jsx).toContain("Dialog.Title");
+  });
+
+  it("skips unknown components with warning", async () => {
+    const result = await handleCompose(registry, {
+      components: ["Dialog", "FakeComponent"],
+    });
+    expect(result.jsx).toContain("Dialog");
+    expect(result.warnings).toContain('Component "FakeComponent" not found');
+  });
+});
+```
+
+- [ ] **Step 2: Implement compose tool**
+
+Create `packages/mcp/src/tools/compose.ts`:
+
+```typescript
+import type { ComponentRegistry } from "../registry.js";
+
+interface ComposeInput {
+  components: string[];
+  intent?: string;
+}
+
+interface ComposeResult {
+  jsx: string;
+  imports: string[];
+  warnings: string[];
+}
+
+/** Converts PascalCase to kebab-case. */
+function toKebab(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/** Generates JSX snippet for a single component using its required parts. */
+function generateComponentJsx(name: string, parts: readonly string[], requiredParts: readonly string[], indent: number): string {
+  const pad = "  ".repeat(indent);
+  const lines: string[] = [];
+
+  const hasRoot = parts.includes("Root");
+  if (hasRoot) {
+    lines.push(`${pad}<${name}>`);
+    for (const part of requiredParts) {
+      if (part === "Root") continue;
+      lines.push(`${pad}  <${name}.${part}>...</${name}.${part}>`);
+    }
+    lines.push(`${pad}</${name}>`);
+  } else {
+    lines.push(`${pad}<${name} />`);
+  }
+
+  return lines.join("\n");
+}
+
+/** Handles pettyui.compose — generates composed multi-component JSX. */
+export async function handleCompose(registry: ComponentRegistry, input: ComposeInput): Promise<ComposeResult> {
+  const imports: string[] = [];
+  const jsxParts: string[] = [];
+  const warnings: string[] = [];
+
+  for (const name of input.components) {
+    const component = registry.getComponent(name);
+    if (!component) {
+      warnings.push(`Component "${name}" not found`);
+      continue;
+    }
+
+    imports.push(component.exportPath);
+    jsxParts.push(generateComponentJsx(component.meta.name, component.meta.parts, component.meta.requiredParts, 1));
+  }
+
+  const importLines = imports.map((imp) => {
+    const name = imp.replace("pettyui/", "").split("-").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+    return `import { ${name} } from "${imp}";`;
+  });
+
+  const jsx = [
+    ...importLines,
+    "",
+    "function Component() {",
+    "  return (",
+    "    <>",
+    jsxParts.join("\n"),
+    "    </>",
+    "  );",
+    "}",
+  ].join("\n");
+
+  return { jsx, imports, warnings };
+}
+```
+
+- [ ] **Step 3: Register in server.ts and commit**
+
+```bash
+cd packages/mcp && pnpm vitest run tests/tools/compose.test.ts
+git add packages/mcp/src/tools/compose.ts packages/mcp/tests/tools/compose.test.ts packages/mcp/src/server.ts
+git commit -m "feat(mcp): add pettyui.compose tool for multi-component JSX generation"
+```
+
+---
+
+### Task 8: CLI Wrapper
+
+**Files:**
+- Create: `packages/mcp/src/cli.ts`
+- Create: `packages/mcp/tests/cli.test.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Create `packages/mcp/tests/cli.test.ts`:
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { parseCommand } from "../src/cli.js";
+
+describe("CLI parser", () => {
+  it("parses init command", () => {
+    const cmd = parseCommand(["init"]);
+    expect(cmd.command).toBe("init");
+  });
+
+  it("parses add command with component", () => {
+    const cmd = parseCommand(["add", "dialog"]);
+    expect(cmd.command).toBe("add");
+    expect(cmd.args.component).toBe("dialog");
+  });
+
+  it("parses add with target dir", () => {
+    const cmd = parseCommand(["add", "dialog", "--dir", "src/ui"]);
+    expect(cmd.command).toBe("add");
+    expect(cmd.args.component).toBe("dialog");
+    expect(cmd.args.dir).toBe("src/ui");
+  });
+
+  it("parses inspect command", () => {
+    const cmd = parseCommand(["inspect", "dialog"]);
+    expect(cmd.command).toBe("inspect");
+    expect(cmd.args.component).toBe("dialog");
+  });
+
+  it("parses list command", () => {
+    const cmd = parseCommand(["list"]);
+    expect(cmd.command).toBe("list");
+  });
+
+  it("returns help for unknown command", () => {
+    const cmd = parseCommand(["unknown"]);
+    expect(cmd.command).toBe("help");
+  });
+
+  it("returns help for empty args", () => {
+    const cmd = parseCommand([]);
+    expect(cmd.command).toBe("help");
+  });
+});
+```
+
+- [ ] **Step 2: Implement CLI**
+
+Create `packages/mcp/src/cli.ts`:
+
+```typescript
+#!/usr/bin/env node
+import { ComponentRegistry } from "./registry.js";
+import { handleDiscover } from "./tools/discover.js";
+import { handleInspect } from "./tools/inspect.js";
+import { handleAdd } from "./tools/add.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+interface ParsedCommand {
+  command: string;
+  args: Record<string, string>;
+}
+
+/** Parses CLI arguments into a command + args. */
+export function parseCommand(argv: string[]): ParsedCommand {
+  if (argv.length === 0) return { command: "help", args: {} };
+
+  const command = argv[0];
+  const args: Record<string, string> = {};
+
+  if (["add", "inspect", "discover"].includes(command) && argv.length > 1) {
+    args.component = argv[1];
+  }
+
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === "--dir" && argv[i + 1]) {
+      args.dir = argv[i + 1];
+      i++;
+    }
+  }
+
+  if (!["init", "add", "inspect", "list", "discover", "help"].includes(command)) {
+    return { command: "help", args: {} };
+  }
+
+  return { command, args };
+}
+
+const HELP_TEXT = `
+pettyui — AI-native component library CLI
+
+Commands:
+  pettyui init                    Set up tokens, utils, tsconfig paths
+  pettyui add <component>         Copy styled component to your project
+  pettyui inspect <component>     Show component schema and usage
+  pettyui list                    List all available components
+  pettyui discover <intent>       Search components by intent
+
+Options:
+  --dir <path>    Target directory for add (default: src/components/ui)
+`;
+
+/** Runs the CLI with given arguments. */
+export async function runCli(argv: string[]): Promise<void> {
+  const { command, args } = parseCommand(argv);
+  const registry = new ComponentRegistry();
+
+  switch (command) {
+    case "help": {
+      console.log(HELP_TEXT);
+      break;
+    }
+    case "list": {
+      const components = registry.listComponents();
+      console.log(`\n${components.length} components available:\n`);
+      for (const c of components) {
+        const styled = c.hasStyledVersion ? " [styled]" : "";
+        console.log(`  ${c.meta.name}${styled} — ${c.meta.description}`);
+      }
+      console.log("");
+      break;
+    }
+    case "inspect": {
+      if (!args.component) { console.error("Usage: pettyui inspect <component>"); break; }
+      const result = await handleInspect(registry, { component: args.component });
+      if (!result) { console.error(`Component "${args.component}" not found`); break; }
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+    case "discover": {
+      if (!args.component) { console.error("Usage: pettyui discover <intent>"); break; }
+      const results = await handleDiscover(registry, { intent: args.component });
+      if (results.length === 0) { console.log("No matching components found."); break; }
+      for (const r of results) {
+        console.log(`  ${r.name} (${r.score}) — ${r.description}`);
+      }
+      break;
+    }
+    case "add": {
+      if (!args.component) { console.error("Usage: pettyui add <component>"); break; }
+      const result = await handleAdd(registry, { component: args.component, targetDir: args.dir });
+      if (!result) { console.error(`No styled version available for "${args.component}"`); break; }
+      for (const file of result.files) {
+        const dir = path.dirname(file.path);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file.path, file.content, "utf-8");
+        console.log(`  Created ${file.path}`);
+      }
+      console.log(`\n  Dependencies: ${result.dependencies.join(", ")}`);
+      break;
+    }
+    case "init": {
+      console.log("pettyui init — setting up project...");
+      const tokensPath = "src/styles/tokens.css";
+      const utilsPath = "src/lib/utils.ts";
+      const registryDir = path.resolve(import.meta.dirname, "../../registry/src");
+      const tokensSource = path.join(registryDir, "tokens.css");
+      const utilsSource = path.join(registryDir, "utils.ts");
+
+      if (fs.existsSync(tokensSource)) {
+        fs.mkdirSync(path.dirname(tokensPath), { recursive: true });
+        fs.copyFileSync(tokensSource, tokensPath);
+        console.log(`  Created ${tokensPath}`);
+      }
+      if (fs.existsSync(utilsSource)) {
+        fs.mkdirSync(path.dirname(utilsPath), { recursive: true });
+        fs.copyFileSync(utilsSource, utilsPath);
+        console.log(`  Created ${utilsPath}`);
+      }
+      console.log("\n  Done! Add pettyui as a dependency and import tokens.css in your app.");
+      break;
+    }
+  }
+}
+
+// Run if called directly
+const args = process.argv.slice(2);
+if (args.length > 0 || !process.stdin.isTTY) {
+  runCli(args);
+}
+```
+
+- [ ] **Step 3: Run tests and commit**
+
+```bash
+cd packages/mcp && pnpm vitest run tests/cli.test.ts
+git add packages/mcp/src/cli.ts packages/mcp/tests/cli.test.ts
+git commit -m "feat(mcp): add CLI wrapper with init, add, inspect, list, discover commands"
+```
+
+---
+
+### Task 9: Final Server Assembly + Verification
+
+**Files:**
+- Modify: `packages/mcp/src/server.ts` — ensure all 5 tools registered
+- Modify: `packages/mcp/package.json` — verify bin entries
+
+- [ ] **Step 1: Verify server.ts has all 5 tools registered**
+
+Read `packages/mcp/src/server.ts` and ensure it registers: `pettyui.discover`, `pettyui.inspect`, `pettyui.validate`, `pettyui.add`, `pettyui.compose`.
+
+- [ ] **Step 2: Run full test suite**
+
+```bash
+cd packages/mcp && pnpm vitest run
+```
+
+Expected: All tests pass across registry, tools, and CLI.
+
+- [ ] **Step 3: Build the MCP package**
+
+```bash
+cd packages/mcp && pnpm build
+```
+
+Expected: Clean build.
+
+- [ ] **Step 4: Verify MCP server starts**
+
+```bash
+cd packages/mcp && echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | node dist/index.js
+```
+
+Expected: Returns JSON-RPC response with server capabilities listing all 5 tools.
+
+- [ ] **Step 5: Verify CLI works**
+
+```bash
+cd packages/mcp && node dist/cli.js list
+```
+
+Expected: Lists all 39 components with descriptions.
+
+- [ ] **Step 6: Run full monorepo test suite**
+
+```bash
+cd /Users/matsbosson/Documents/StayThree/PettyUI && pnpm test
+```
+
+Expected: All packages pass (core: 445 tests, registry: 3 tests, mcp: all tests).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/mcp/
+git commit -m "feat(mcp): complete MCP server with 5 tools + CLI, Phase 3 done"
+```