composter-cli 1.0.4 → 1.0.6

package/README.md

@@ -4,44 +4,564 @@
 
 [![npm version](https://img.shields.io/npm/v/composter-cli.svg)](https://www.npmjs.com/package/composter-cli)
 [![license](https://img.shields.io/npm/l/composter-cli.svg)](https://github.com/binit2-1/Composter/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/composter-cli.svg)](https://nodejs.org)
 
 **Composter** is like your personal shadcn/ui — but for YOUR components. Push components from any project, pull them into new ones, and let AI assistants access your vault via MCP.
 
+---
+
+## 🎯 Why Composter?
+
+Ever built an amazing component and wanted to reuse it in another project? Tired of copy-pasting files and forgetting dependencies? Composter solves this:
+
+- **No more copy-paste chaos** — Push once, pull anywhere
+- **Dependencies tracked automatically** — Never forget to install packages again
+- **Smart bundling** — Relative imports are bundled, npm packages are tracked
+- **AI-ready** — Let Claude, Cursor, or Copilot access your vault via MCP
+- **Private by default** — Your components, your vault, your control
+
+---
+
 ## ✨ Features
 
-- **📤 Push** — Upload components with all their local dependencies auto-bundled
-- **📥 Pull** — Download components into any project with dependency detection
-- **📁 Categories** — Organize components into logical groups
-- **🔗 Smart Bundling** — Automatically crawls and bundles relative imports
-- **📦 Dependency Tracking** — Detects npm packages and alerts you to missing ones
-- **🤖 MCP Ready** — Works with Claude, Cursor, and other AI assistants
+| Feature | Description |
+|---------|-------------|
+| 📤 **Push** | Upload components with all local dependencies auto-bundled |
+| 📥 **Pull** | Download components with original folder structure preserved |
+| 📁 **Categories** | Organize components into logical groups (UI, Hooks, Utils) |
+| 🔗 **Smart Bundling** | Automatically crawls `./` and `@/` imports |
+| 📦 **Dependency Detection** | Reads your `package.json` and tracks npm packages |
+| ⚠️ **Missing Dep Alerts** | Tells you exactly what to `npm install` after pulling |
+| 🤖 **MCP Integration** | Works with AI assistants via Model Context Protocol |
+
+---
 
 ## 📦 Installation
 
-npm install -g composter-cli## 🚀 Quick Start
+### Global Install (Recommended)
+
+```bash
+npm install -g composter-cli
+```
+
+### Using npx
+
+```bash
+npx composter-cli login
+```
+
+### Verify Installation
+
+```bash
+composter --version
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Create an Account
+
+Visit **[composter.vercel.app](https://composter.vercel.app)** and sign up.
+
+### 2. Login via CLI
+
+```bash
+composter login
+```
+
+```
+=== Composter Login ===
+? Email: you@example.com
+? Password: ********
 
-# 1. Create an account at https://composter.vercel.app
+Logged in successfully!
+Session expires: 2025-01-09T12:00:00.000Z
+```
 
-# 2. Login to your vault
+### 3. Create a Category
+
+```bash
+composter mkcat ui
+```
+
+### 4. Push Your First Component
+
+```bash
+composter push ui "Fancy Button" ./src/components/FancyButton.tsx
+```
+
+```
+Scanning FancyButton.tsx and its dependencies...
+📦 Bundled 3 file(s) and detected 2 external package(s).
+✅ Success! Component 'Fancy Button' pushed to 'ui'.
+```
+
+### 5. Pull It In Another Project
+
+```bash
+composter pull ui "Fancy Button" ./src/components/
+```
+
+```
+⏳ Fetching 'Fancy Button' from 'ui'...
+📦 Unpacking 3 file(s) into: /Users/you/new-project/src/components
+   + FancyButton.tsx
+   + FancyButton.module.css
+   + useButtonAnimation.ts
+
+⚠️  Missing Dependencies (Run this to fix):
+   npm install framer-motion clsx
+
+✅ Component 'Fancy Button' pulled successfully!
+```
+
+---
+
+## 📖 Commands Reference
+
+### `composter login`
+
+Authenticate with your Composter account.
+
+```bash
 composter login
+```
+
+**What happens:**
+- Prompts for email and password
+- Creates a JWT session token
+- Stores session at `~/.config/composter/session.json`
+- Session lasts 30 days
+
+---
+
+### `composter mkcat <category-name>`
+
+Create a new category to organize your components.
+
+```bash
+composter mkcat hooks
+```
+
+**Output:**
+```
+Category 'hooks' created successfully!
+ID: clx1234567890
+```
+
+**Rules:**
+| Rule | Example |
+|------|---------|
+| No spaces | ❌ `my buttons` → ✅ `buttons` |
+| Max 10 characters | ❌ `superlongname` → ✅ `utils` |
+| Unique per user | Each category name must be unique |
+
+---
+
+### `composter ls`
+
+List all your categories.
+
+```bash
+composter ls
+```
+
+**Output:**
+```
+ui          hooks       utils       layouts     forms
+```
+
+---
+
+### `composter push <category> <title> <file-path>`
+
+Push a component to your vault.
+
+```bash
+composter push ui "Data Table" ./src/components/DataTable/index.tsx
+```
+
+**Arguments:**
+
+| Argument | Description | Example |
+|----------|-------------|---------|
+| `category` | Target category name | `ui` |
+| `title` | Human-readable component name | `"Data Table"` |
+| `file-path` | Entry file path | `./src/components/DataTable.tsx` |
+
+**What gets bundled:**
+```
+Your Entry File
+│
+├── ./relative/imports      → ✅ Bundled into package
+├── @/alias/imports         → ✅ Bundled (assumes @/ = src/)
+├── ./styles.css            → ✅ Bundled
+│
+└── External packages       → 📦 Tracked as dependencies
+    ├── react               
+    ├── framer-motion       
+    └── @tanstack/react-table
+```
+
+**Example Output:**
+```
+Scanning DataTable.tsx and its dependencies...
+📦 Bundled 5 file(s) and detected 4 external package(s).
+✅ Success! Component 'Data Table' pushed to 'ui'.
+```
+
+---
+
+### `composter pull <category> <title> <target-directory>`
+
+Pull a component from your vault.
+
+```bash
+composter pull ui "Data Table" ./src/components/
+```
+
+**Arguments:**
+
+| Argument | Description | Example |
+|----------|-------------|---------|
+| `category` | Source category name | `ui` |
+| `title` | Component name to pull | `"Data Table"` |
+| `target-directory` | Where to save files | `./src/components/` |
+
+**What happens:**
+1. Fetches component bundle from your vault
+2. Recreates original folder structure
+3. Writes all files to target directory
+4. Checks your `package.json` for missing dependencies
+5. Suggests `npm install` command if needed
+
+**Example Output:**
+```
+⏳ Fetching 'Data Table' from 'ui'...
+📦 Unpacking 5 file(s) into: /Users/you/project/src/components
+   + DataTable/index.tsx
+   + DataTable/DataTableHeader.tsx
+   + DataTable/DataTableRow.tsx
+   + DataTable/DataTablePagination.tsx
+   + DataTable/data-table.css
+
+⚠️  Missing Dependencies (Run this to fix):
+   npm install @tanstack/react-table lucide-react
+
+✅ Component 'Data Table' pulled successfully!
+```
+
+---
+
+## 🔧 How Smart Bundling Works
+
+When you push a component, the CLI performs intelligent dependency crawling:
+
+### Import Resolution
+
+```tsx
+// Entry: src/components/Button.tsx
+
+import { cn } from "@/lib/utils"           // ✅ Bundled (alias import)
+import { useToggle } from "./hooks/toggle" // ✅ Bundled (relative import)
+import "./button.css"                       // ✅ Bundled (CSS import)
+import { motion } from "framer-motion"      // 📦 Tracked as npm dependency
+import React from "react"                   // 📦 Tracked as npm dependency
+```
+
+### Alias Support
+
+The `@/` alias is automatically resolved to your `src/` directory:
+
+```
+@/components/Button  →  src/components/Button
+@/lib/utils          →  src/lib/utils
+@/hooks/useAuth      →  src/hooks/useAuth
+```
+
+### File Extensions
+
+The crawler automatically resolves these extensions:
+
+```
+import { Button } from "./Button"
+                           ↓
+Tries: Button.tsx → Button.ts → Button.jsx → Button.js → Button/index.tsx
+```
+
+### Package Version Detection
+
+npm dependencies are tracked with versions from your `package.json`:
+
+```json
+// Your package.json
+{
+  "dependencies": {
+    "framer-motion": "^10.16.0",
+    "clsx": "^2.0.0"
+  }
+}
 
-# 3. Create a category
-composter mkcat buttons
+// Stored with component
+{
+  "framer-motion": "^10.16.0",
+  "clsx": "^2.0.0"
+}
+```
 
-# 4. Push a component
-composter push buttons "Animated Button" ./src/components/Button.tsx
+---
 
-# 5. Pull it in another project
-composter pull buttons "Animated Button" ./src/components/## 📖 Commands
+## 🤖 AI Integration (MCP)
+
+Composter includes a built-in Model Context Protocol (MCP) server that lets AI assistants interact with your vault directly.
+
+### Quick Setup
+
+```bash
+# One command to configure your AI assistant
+npx composter-cli@latest mcp init --client claude
+```
+
+**Supported clients:**
+- `claude` — Claude Desktop
+- `cursor` — Cursor IDE
+- `vscode` — VS Code with Copilot
+- `windsurf` — Windsurf IDE
+
+### MCP Commands
 
 | Command | Description |
 |---------|-------------|
-| `composter login` | Authenticate with your account |
-| `composter mkcat <name>` | Create a new category |
-| `composter ls` | List all categories |
-| `composter push <category> <title> <file>` | Push a component |
-| `composter pull <category> <title> <dir>` | Pull a component |
+| `composter mcp init --client <name>` | Configure MCP for an AI assistant |
+| `composter mcp serve` | Start MCP server directly (testing) |
+| `composter mcp info` | Show MCP configuration info |
+
+### Options
+
+```bash
+# Configure for Claude Desktop
+composter mcp init --client claude
+
+# Configure for Cursor
+composter mcp init --client cursor
+
+# Use localhost backend (development)
+composter mcp init --client claude --dev
+
+# Show manual config instructions
+composter mcp info
+```
+
+### Available AI Tools
+
+Once configured, your AI assistant can use these tools:
+
+| Tool | Description |
+|------|-------------|
+| `search_components` | Search your vault by name or category |
+| `list_categories` | List all your categories |
+| `list_components` | List components in a category |
+| `read_component` | Read full source code of a component |
+
+### Example AI Prompts
+
+After setup, you can ask your AI:
+- *"Search my Composter vault for button components"*
+- *"What categories do I have in Composter?"*
+- *"Read the DataTable component from my ui category"*
+- *"List all components in my hooks category"*
+
+### Development Mode
+
+For local development with `localhost:3000` backend:
+
+```bash
+# Initialize with dev flag
+composter mcp init --client claude --dev
+
+# Or set environment variable
+COMPOSTER_DEV=true composter mcp serve
+```
+
+---
+
+## 📂 File Locations
+
+| File | Location | Purpose |
+|------|----------|---------|
+| Session | `~/.config/composter/session.json` | JWT auth token |
+| Config Dir | `~/.config/composter/` | All CLI data |
+
+### Session File Structure
+
+```json
+{
+  "jwt": "eyJhbGciOiJSUzI1NiIs...",
+  "cookies": "session_token=...",
+  "createdAt": "2024-12-10T10:00:00.000Z",
+  "expiresAt": "2025-01-09T10:00:00.000Z"
+}
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### "You must be logged in"
+
+Your session doesn't exist or has expired.
+
+```bash
+composter login
+```
+
+### "Session expired"
+
+Sessions last 30 days. Re-authenticate:
+
+```bash
+composter login
+```
+
+### "Invalid category name"
+
+Category names have strict rules:
+
+```bash
+# ❌ These will fail
+composter mkcat "My Components"    # No spaces
+composter mkcat verylongcatname    # Max 10 chars
+
+# ✅ These work
+composter mkcat ui
+composter mkcat hooks
+composter mkcat utils
+```
+
+### "File not found" when pushing
+
+Check your file path:
+
+```bash
+# Make sure you're in the right directory
+pwd
+
+# Use relative path from current directory
+composter push ui "Button" ./src/components/Button.tsx
+
+# Or use absolute path
+composter push ui "Button" /Users/me/project/src/components/Button.tsx
+```
+
+### "Component not found" when pulling
+
+- Check the exact component title (case-sensitive)
+- Verify the category name
+- List your components on the web dashboard
+
+### Missing dependencies after pull
+
+The CLI tells you what's missing. Just run:
+
+```bash
+npm install package1 package2 package3
+```
+
+### Network errors
+
+- Check your internet connection
+- Verify the backend is accessible: `https://composter.onrender.com/api/health`
+- Try logging in again
+
+---
+
+## 🌐 Web Dashboard
+
+Manage your components visually at **[composter.vercel.app](https://composter.vercel.app)**
+
+- 📋 Browse all components
+- 👁️ Live code preview with Sandpack
+- ✏️ Edit component metadata
+- 📊 View dependency graphs
+- 📋 Copy code snippets
+- 🗑️ Delete components
+
+---
+
+## 🔒 Security
+
+| Feature | Description |
+|---------|-------------|
+| 🔐 JWT Auth | Secure token-based authentication |
+| 🏠 Local Storage | Tokens stored locally, never shared |
+| 🔒 User Isolation | Each vault is completely private |
+| 🌐 HTTPS | All API traffic encrypted |
+| ⏰ Expiring Sessions | 30-day token lifetime |
+
+---
+
+## 📋 Examples
+
+### Push a Shadcn-style Component
+
+```bash
+# Push a button with all its dependencies
+composter push ui "Shadcn Button" ./src/components/ui/button.tsx
+```
+
+### Push a Custom Hook
+
+```bash
+composter push hooks "useLocalStorage" ./src/hooks/useLocalStorage.ts
+```
+
+### Push a Full Feature
+
+```bash
+# Push a data table that imports multiple files
+composter push features "User Table" ./src/features/users/UserTable.tsx
+```
+
+### Pull Into a New Project
+
+```bash
+# Create components folder if needed
+mkdir -p src/components
+
+# Pull your button
+composter pull ui "Shadcn Button" ./src/components/ui/
+
+# Install any missing deps
+npm install
+```
+
+---
+
+## 🔗 Links
+
+| Resource | URL |
+|----------|-----|
+| 🌐 Web App | [composter.vercel.app](https://composter.vercel.app) |
+| 📦 npm | [npmjs.com/package/composter-cli](https://www.npmjs.com/package/composter-cli) |
+| 💻 GitHub | [github.com/binit2-1/Composter](https://github.com/binit2-1/Composter) |
+| 🐛 Issues | [Report a bug](https://github.com/binit2-1/Composter/issues) |
+| 🤖 MCP Docs | [MCP Setup Guide](https://github.com/binit2-1/Composter/tree/main/mcp) |
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](https://github.com/binit2-1/Composter/blob/main/CONTRIBUTING.md)
+
+---
+
+## 📄 License
+
+MIT © [binit2-1](https://github.com/binit2-1)
 
-## 🔧 Smart Bundling
+---
 
-When you push, the CLI automatically bundles all local imports:
+<p align="center">
+  <b>Built with ❤️ for developers who hate copy-pasting components</b>
+</p>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "composter-cli",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "type": "module",
-  "description": "Your personal vault for React components. Push, pull, and sync reusable components across projects — like shadcn/ui but for YOUR code.",
+  "description": "Your personal vault for React components. Push, pull, and sync reusable components across projects — like shadcn/ui but for YOUR code. Includes MCP server for AI assistants.",
   "main": "src/index.js",
   "bin": {
     "composter": "./bin/composter.js"
@@ -22,7 +22,11 @@
     "developer-tools",
     "productivity",
     "mcp",
-    "ai-tools"
+    "ai-tools",
+    "claude",
+    "cursor",
+    "copilot",
+    "model-context-protocol"
   ],
   "author": "binit2-1",
   "license": "MIT",
@@ -38,9 +42,11 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.23.0",
     "commander": "^14.0.2",
     "dotenv": "^16.4.5",
     "inquirer": "^13.0.1",
-    "node-fetch": "^3.3.2"
+    "node-fetch": "^3.3.2",
+    "zod": "^3.23.0"
   }
 }

package/src/commands/mcp.js

@@ -0,0 +1,238 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { loadSession } from "../utils/session.js";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Get the path to the MCP server script
+function getMcpServerPath() {
+  return path.resolve(__dirname, "../mcp/server.js");
+}
+
+// Client configuration templates
+const CLIENT_CONFIGS = {
+  claude: {
+    name: "Claude Desktop",
+    configPath: () => {
+      if (process.platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+      } else if (process.platform === "win32") {
+        return path.join(process.env.APPDATA, "Claude", "claude_desktop_config.json");
+      } else {
+        return path.join(os.homedir(), ".config", "claude", "claude_desktop_config.json");
+      }
+    },
+    generateConfig: (serverPath, cwd) => ({
+      mcpServers: {
+        composter: {
+          command: "node",
+          args: [serverPath],
+          cwd: cwd,
+        },
+      },
+    }),
+  },
+  cursor: {
+    name: "Cursor",
+    configPath: () => {
+      return path.join(process.cwd(), ".cursor", "mcp.json");
+    },
+    generateConfig: (serverPath, cwd) => ({
+      composter: {
+        command: "node",
+        args: [serverPath],
+        cwd: cwd,
+      },
+    }),
+  },
+  vscode: {
+    name: "VS Code (Copilot)",
+    configPath: () => {
+      return path.join(process.cwd(), ".vscode", "mcp.json");
+    },
+    generateConfig: (serverPath, cwd) => ({
+      servers: {
+        composter: {
+          command: "node",
+          args: [serverPath],
+          cwd: cwd,
+        },
+      },
+    }),
+  },
+  windsurf: {
+    name: "Windsurf",
+    configPath: () => {
+      return path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json");
+    },
+    generateConfig: (serverPath, cwd) => ({
+      mcpServers: {
+        composter: {
+          command: "node",
+          args: [serverPath],
+          cwd: cwd,
+        },
+      },
+    }),
+  },
+};
+
+// Initialize MCP for a specific client
+export async function mcpInit(client, options = {}) {
+  // Validate client
+  const clientConfig = CLIENT_CONFIGS[client?.toLowerCase()];
+  if (!clientConfig) {
+    console.log(`❌ Unknown client: ${client}`);
+    console.log(`\nSupported clients:`);
+    Object.entries(CLIENT_CONFIGS).forEach(([key, val]) => {
+      console.log(`  - ${key} (${val.name})`);
+    });
+    return;
+  }
+
+  // Check if user is logged in
+  const session = loadSession();
+  if (!session?.jwt) {
+    console.log("❌ You must be logged in first. Run: composter login");
+    return;
+  }
+
+  const serverPath = getMcpServerPath();
+  const cwd = options.global ? path.dirname(serverPath) : process.cwd();
+  const configPath = clientConfig.configPath();
+  const configDir = path.dirname(configPath);
+
+  console.log(`\n🔧 Setting up Composter MCP for ${clientConfig.name}...\n`);
+
+  // Generate the config snippet
+  const newConfig = clientConfig.generateConfig(serverPath, cwd);
+
+  // Check if config file exists
+  let existingConfig = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      existingConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      console.log(`📄 Found existing config at: ${configPath}`);
+    } catch {
+      console.log(`⚠️  Existing config is invalid, will create new one.`);
+    }
+  }
+
+  // Merge configs
+  let mergedConfig;
+  if (client === "claude" || client === "windsurf") {
+    mergedConfig = {
+      ...existingConfig,
+      mcpServers: {
+        ...existingConfig.mcpServers,
+        ...newConfig.mcpServers,
+      },
+    };
+  } else if (client === "vscode") {
+    mergedConfig = {
+      ...existingConfig,
+      servers: {
+        ...existingConfig.servers,
+        ...newConfig.servers,
+      },
+    };
+  } else {
+    // Cursor - direct merge
+    mergedConfig = {
+      ...existingConfig,
+      ...newConfig,
+    };
+  }
+
+  // Create directory if needed
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+    console.log(`📁 Created directory: ${configDir}`);
+  }
+
+  // Write config
+  fs.writeFileSync(configPath, JSON.stringify(mergedConfig, null, 2), "utf-8");
+  console.log(`✅ Config written to: ${configPath}`);
+
+  // Print success message
+  console.log(`
+╔════════════════════════════════════════════════════════════════╗
+║                    🎉 MCP Setup Complete!                      ║
+╠════════════════════════════════════════════════════════════════╣
+║                                                                ║
+║  Composter MCP server has been configured for ${clientConfig.name.padEnd(14)}  ║
+║                                                                ║
+║  Next steps:                                                   ║
+║  1. Restart ${clientConfig.name.padEnd(50)} ║
+║  2. Look for "Composter" in your MCP tools                     ║
+║                                                                ║
+║  Available tools:                                              ║
+║  • search_components - Search your component vault             ║
+║  • list_categories   - List all your categories                ║
+║  • list_components   - List components in a category           ║
+║  • read_component    - Read full source code                   ║
+║                                                                ║
+╚════════════════════════════════════════════════════════════════╝
+`);
+
+  // Dev mode hint
+  if (options.dev) {
+    console.log(`\n💡 Dev mode: Set COMPOSTER_DEV=true to use localhost:3000`);
+  }
+}
+
+// Serve MCP server directly (for testing)
+export async function mcpServe(options = {}) {
+  const session = loadSession();
+  if (!session?.jwt) {
+    console.log("❌ You must be logged in first. Run: composter login");
+    return;
+  }
+
+  console.log("🚀 Starting Composter MCP server...");
+  console.log("   Press Ctrl+C to stop\n");
+
+  // Set dev mode if requested
+  if (options.dev) {
+    process.env.COMPOSTER_DEV = "true";
+    console.log("📡 Dev mode: Using localhost:3000");
+  }
+
+  // Dynamic import and run the server
+  const serverPath = getMcpServerPath();
+  await import(serverPath);
+}
+
+// Show MCP configuration info
+export function mcpInfo() {
+  const serverPath = getMcpServerPath();
+  const session = loadSession();
+
+  console.log(`
+╔════════════════════════════════════════════════════════════════╗
+║                  Composter MCP Information                     ║
+╠════════════════════════════════════════════════════════════════╣
+
+  Server path:  ${serverPath}
+  Logged in:    ${session?.jwt ? "✅ Yes" : "❌ No (run 'composter login')"}
+  
+  Manual configuration:
+  
+  {
+    "composter": {
+      "command": "node",
+      "args": ["${serverPath}"]
+    }
+  }
+
+  Environment variables:
+  • COMPOSTER_DEV=true     - Use localhost:3000 backend
+  • COMPOSTER_API_URL=...  - Custom API URL
+
+╚════════════════════════════════════════════════════════════════╝
+`);
+}
+

package/src/index.js

@@ -6,6 +6,7 @@ import { mkcat } from "./commands/mkcat.js";
 import { listCategories } from "./commands/listCat.js";
 import { pushComponent } from "./commands/push.js";
 import { pullComponent } from "./commands/pull.js";
+import { mcpInit, mcpServe, mcpInfo } from "./commands/mcp.js";
 import { createRequire } from "module";
 
 const require = createRequire(import.meta.url);
@@ -49,4 +50,34 @@ program
     pullComponent(category, title, filepath);
   });
 
+// MCP Commands
+const mcp = program
+  .command("mcp")
+  .description("Manage MCP (Model Context Protocol) server for AI assistants");
+
+mcp
+  .command("init")
+  .description("Initialize MCP server for an AI assistant")
+  .option("-c, --client <client>", "AI client to configure (claude, cursor, vscode, windsurf)", "claude")
+  .option("-g, --global", "Configure globally instead of project-specific")
+  .option("-d, --dev", "Use localhost:3000 backend (development mode)")
+  .action((options) => {
+    mcpInit(options.client, options);
+  });
+
+mcp
+  .command("serve")
+  .description("Start the MCP server directly (for testing)")
+  .option("-d, --dev", "Use localhost:3000 backend (development mode)")
+  .action((options) => {
+    mcpServe(options);
+  });
+
+mcp
+  .command("info")
+  .description("Show MCP configuration information")
+  .action(() => {
+    mcpInfo();
+  });
+
 program.parse(process.argv);

package/src/mcp/server.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { loadSession } from "../utils/session.js";
+import fetch from "node-fetch";
+
+// Redirect console.log to stderr (MCP uses stdout for protocol)
+const originalLog = console.log;
+console.log = (...args) => console.error(...args);
+
+// Determine base URL - supports both dev and production
+function getBaseUrl() {
+  // Check for explicit env var first
+  if (process.env.COMPOSTER_API_URL) {
+    return process.env.COMPOSTER_API_URL;
+  }
+  // Check for dev mode
+  if (process.env.COMPOSTER_DEV === "true" || process.env.NODE_ENV === "development") {
+    return "http://localhost:3000/api";
+  }
+  // Default to production
+  return "https://composter.onrender.com/api";
+}
+
+const BASE_URL = getBaseUrl();
+
+// API request helper with JWT auth
+async function apiRequest(path, options = {}) {
+  const session = loadSession();
+  
+  if (!session?.jwt) {
+    throw new Error("Not authenticated. Run 'composter login' first.");
+  }
+
+  const headers = {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${session.jwt}`,
+    ...options.headers,
+  };
+
+  const res = await fetch(`${BASE_URL}${path}`, {
+    ...options,
+    headers,
+  });
+
+  if (res.status === 401) {
+    throw new Error("Session expired. Run 'composter login' again.");
+  }
+
+  return res;
+}
+
+// Create the MCP server with tools
+function createComposterMcpServer() {
+  const server = new McpServer({
+    name: "Composter",
+    version: "1.0.0",
+  });
+
+  // Tool: Search components
+  server.tool(
+    "search_components",
+    "Search for React components in your Composter vault by title or category name. Returns matching components with IDs and categories.",
+    {
+      query: z.string().describe("Search term for component title or category name"),
+    },
+    async ({ query }) => {
+      try {
+        const res = await apiRequest(`/components/search?q=${encodeURIComponent(query)}`, { method: "GET" });
+        
+        if (!res.ok) {
+          const error = await res.json().catch(() => ({}));
+          return {
+            content: [{ type: "text", text: `Error searching: ${error.message || res.statusText}` }],
+          };
+        }
+
+        const data = await res.json();
+        const components = data.components || [];
+
+        if (components.length === 0) {
+          return {
+            content: [{ type: "text", text: "No components found matching that query." }],
+          };
+        }
+
+        const formatted = components.map((c) =>
+          `- **${c.title}** (Category: ${c.category?.name || "unknown"}) [ID: ${c.id}]`
+        ).join("\n");
+
+        return {
+          content: [{ type: "text", text: `Found ${components.length} component(s):\n\n${formatted}` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+        };
+      }
+    }
+  );
+
+  // Tool: List categories
+  server.tool(
+    "list_categories",
+    "List all categories in your Composter vault.",
+    {},
+    async () => {
+      try {
+        const res = await apiRequest("/categories");
+        
+        if (!res.ok) {
+          const error = await res.json().catch(() => ({}));
+          return {
+            content: [{ type: "text", text: `Error: ${error.message || res.statusText}` }],
+          };
+        }
+
+        const data = await res.json();
+        const categories = data.categories || [];
+
+        if (categories.length === 0) {
+          return {
+            content: [{ type: "text", text: "No categories found. Create one with 'composter mkcat <name>'." }],
+          };
+        }
+
+        const formatted = categories.map((c) => `- ${c.name}`).join("\n");
+
+        return {
+          content: [{ type: "text", text: `Your categories:\n\n${formatted}` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+        };
+      }
+    }
+  );
+
+  // Tool: Read component
+  server.tool(
+    "read_component",
+    "Read the full source code of a React component from your vault. Returns the code, category, dependencies, and creation date.",
+    {
+      category: z.string().describe("The category name the component belongs to"),
+      title: z.string().describe("The title/name of the component to read"),
+    },
+    async ({ category, title }) => {
+      try {
+        const res = await apiRequest(
+          `/components?category=${encodeURIComponent(category)}&title=${encodeURIComponent(title)}`
+        );
+
+        if (res.status === 404) {
+          return {
+            content: [{ type: "text", text: `Component "${title}" not found in category "${category}".` }],
+          };
+        }
+
+        if (!res.ok) {
+          const error = await res.json().catch(() => ({}));
+          return {
+            content: [{ type: "text", text: `Error: ${error.message || res.statusText}` }],
+          };
+        }
+
+        const data = await res.json();
+        const component = data.component;
+
+        if (!component) {
+          return {
+            content: [{ type: "text", text: `Component "${title}" not found.` }],
+          };
+        }
+
+        // Parse code - could be JSON (multi-file) or string (single file)
+        let codeOutput = "";
+        try {
+          const files = JSON.parse(component.code);
+          codeOutput = Object.entries(files)
+            .map(([path, content]) => `### ${path}\n\`\`\`tsx\n${content}\n\`\`\``)
+            .join("\n\n");
+        } catch {
+          codeOutput = `\`\`\`tsx\n${component.code}\n\`\`\``;
+        }
+
+        // Format dependencies
+        let depsOutput = "";
+        if (component.dependencies && Object.keys(component.dependencies).length > 0) {
+          const deps = Object.entries(component.dependencies)
+            .map(([pkg, ver]) => `- ${pkg}: ${ver}`)
+            .join("\n");
+          depsOutput = `\n\n**Dependencies:**\n${deps}`;
+        }
+
+        const output = `# ${component.title}
+
+**Category:** ${category}
+**Created:** ${new Date(component.createdAt).toLocaleDateString()}
+${depsOutput}
+
+## Source Code
+
+${codeOutput}`;
+
+        return {
+          content: [{ type: "text", text: output }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+        };
+      }
+    }
+  );
+
+  // Tool: List components in category
+  server.tool(
+    "list_components",
+    "List all components in a specific category.",
+    {
+      category: z.string().describe("The category name to list components from"),
+    },
+    async ({ category }) => {
+      try {
+        const res = await apiRequest(`/components/list-by-category?category=${encodeURIComponent(category)}`, { method: "GET" });
+        
+        if (!res.ok) {
+          const error = await res.json().catch(() => ({}));
+          return {
+            content: [{ type: "text", text: `Error: ${error.message || res.statusText}` }],
+          };
+        }
+
+        const data = await res.json();
+        const components = data.components || [];
+
+        if (components.length === 0) {
+          return {
+            content: [{ type: "text", text: `No components found in category "${category}".` }],
+          };
+        }
+
+        const formatted = components.map((c) => 
+          `- **${c.title}** (created: ${new Date(c.createdAt).toLocaleDateString()})`
+        ).join("\n");
+
+        return {
+          content: [{ type: "text", text: `Components in "${category}":\n\n${formatted}` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+        };
+      }
+    }
+  );
+
+  return server;
+}
+
+// Main entry point
+async function main() {
+  try {
+    // Verify session exists
+    const session = loadSession();
+    if (!session?.jwt) {
+      console.error("❌ No session found. Please run 'composter login' first.");
+      process.exit(1);
+    }
+
+    console.error(`🚀 Composter MCP Server starting...`);
+    console.error(`📡 API: ${BASE_URL}`);
+
+    const server = createComposterMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    console.error("✅ Composter MCP server running on stdio");
+  } catch (error) {
+    console.error("❌ Fatal Error:", error.message);
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+main();
+