Skip to main content
Glama
README.md
<<<<<<< HEAD
# COLLECT-UI-MCP-SERVER
=======
<div align="center">

# 🎨 Collect UI MCP

### *Your AI assistant's personal UI component library*

**Collect Β· Search Β· Recall β€” every snippet, right inside your editor.**

<br/>

[![npm](https://img.shields.io/npm/v/collect-ui-mcp?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/collect-ui-mcp)
[![MCP](https://img.shields.io/badge/MCP-Compatible-8A2BE2?style=for-the-badge&logo=anthropic)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)
[![Node](https://img.shields.io/badge/Node-%E2%89%A518-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
[![PRs](https://img.shields.io/badge/PRs-Welcome-brightgreen?style=for-the-badge)](CONTRIBUTING.md)

<br/>

[**Quick Start**](#-quick-start) Β· [**Features**](#-features) Β· [**Tools**](#-available-tools) Β· [**Examples**](#-example-usage) Β· [**Contributing**](#-contributing)

</div>

---

<div align="center">

### 🧠 *Stop scrolling bookmarks. Start asking.*

> **You:** *"Save this button as `neon-button`, tag it `tailwind` and `dark`."*
>
> **Assistant:** *βœ… Collected β€” 24 lines saved to your library.*

</div>

---

## ✨ Why Collect UI MCP?

<table>
<tr>
<td width="50%" valign="top">

### 😩 The old way

- πŸ”– 47 bookmarks named *"cool button"*
- πŸ“ A folder called `snippets-final-v2-USE-THIS`
- 🧠 You *know* you saved that card somewhere…
- πŸ“‹ Copy-pasting from chat β†’ files β†’ chat β†’ files

</td>
<td width="50%" valign="top">

### ✨ The new way

- πŸ—£οΈ Ask your AI to **save**, **find**, or **fetch** components
- 🏷️ Tag by framework, mood, or use-case
- πŸ” Full-text search across your whole library
- πŸ’Ύ Everything stays **local** and **git-friendly**

</td>
</tr>
</table>

---

## 🎯 Features

<div align="center">

|  | Feature | Description |
|:-:|:--------|:------------|
| πŸ—‚οΈ | **Collect** | Save any UI snippet with a name, tags & description |
| πŸ” | **Search** | Find components by keyword, tag, or framework |
| 🏷️ | **Organize** | Tag by stack β€” React, Vue, Tailwind, CSS… |
| 🧾 | **Retrieve** | Pull full source code straight into chat |
| ✏️ | **Update** | Modify existing entries without leaving your editor |
| πŸ—‘οΈ | **Delete** | Clean up entries in seconds |
| πŸ’Ύ | **Local-first** | Nothing leaves your machine. Ever. |
| 🧩 | **Framework-agnostic** | Works with any UI stack you throw at it |
| ⚑ | **Zero-config** | Point at a folder. Done. |

</div>

---

## πŸš€ Quick Start

<div align="center">

### **3 steps to a smarter UI library**

`Install` β†’ `Configure` β†’ `Ask`

</div>

<br/>

### 1️⃣ &nbsp; Install

```bash
# Global install
npm install -g collect-ui-mcp

# Or use on the fly
npx collect-ui-mcp
```

### 2️⃣ &nbsp; Configure your MCP client

<details open>
<summary><b>🟣 Claude Desktop</b></summary>

<br/>

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "collect-ui": {
      "command": "npx",
      "args": ["-y", "collect-ui-mcp"],
      "env": {
        "COLLECT_UI_DIR": "/absolute/path/to/your/ui-library"
      }
    }
  }
}
```

</details>

<details>
<summary><b>πŸ–±οΈ Cursor</b></summary>

<br/>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "collect-ui": {
      "command": "npx",
      "args": ["-y", "collect-ui-mcp"],
      "env": { "COLLECT_UI_DIR": "/absolute/path/to/your/ui-library" }
    }
  }
}
```

</details>

<details>
<summary><b>πŸ’» VS Code (Continue / Cline)</b></summary>

<br/>

```json
{
  "mcpServers": {
    "collect-ui": {
      "command": "npx",
      "args": ["-y", "collect-ui-mcp"],
      "env": { "COLLECT_UI_DIR": "${workspaceFolder}/.ui-library" }
    }
  }
}
```

</details>

### 3️⃣ &nbsp; Restart your client

> πŸŽ‰ **Done.** Your AI assistant now has the `collect-ui` toolset.

---

## πŸ› οΈ Available Tools

<div align="center">

| &nbsp; | Tool | Description |
|:------:|:-----|:------------|
| πŸ“₯ | `collect_component` | Save a UI snippet with name, code, tags & description |
| πŸ“‹ | `list_components` | List all components β€” filterable by tag |
| πŸ” | `search_components` | Full-text search across names, tags, descriptions |
| πŸ“€ | `get_component` | Fetch the full source + metadata of a component |
| ✏️ | `update_component` | Modify an existing entry |
| πŸ—‘οΈ | `delete_component` | Remove a component from your library |
| 🏷️ | `list_tags` | See every tag currently in use |

</div>

### πŸ“š Resources

| URI | Description |
|:----|:------------|
| `collect-ui://library` | Your entire catalog as JSON |
| `collect-ui://component/{name}` | A single component by name |

### πŸ’¬ Prompts

- **`find-ui-component`** β€” Ask the AI for the best match to a design need
- **`summarize-library`** β€” Get a quick overview of what you've collected

---

## πŸ’‘ Example Usage

<details open>
<summary><b>πŸ’Ύ Saving a component</b></summary>

```
You   β†’  Save this Hero section as "gradient-hero",
         tagged react, tailwind, marketing.

AI    β†’  βœ… Collected "gradient-hero" (React Β· Tailwind)
         Saved 42 lines to your library.
```

</details>

<details>
<summary><b>πŸ” Searching your library</b></summary>

```
You   β†’  What button variants do I have collected?

AI    β†’  You have 3:
         β€’ neon-button   β€” Tailwind Β· dark mode glow
         β€’ ghost-button  β€” CSS Β· minimal outline
         β€’ pill-button   β€” React Β· styled-components
```

</details>

<details>
<summary><b>πŸ“€ Retrieving a component</b></summary>

```
You   β†’  Show me the source of "neon-button".

AI    β†’  [renders full code from your library]
```

</details>

---

## πŸ—ƒοΈ How Data is Stored

Everything lives in a **single folder you control**:

```text
my-ui-library/
β”œβ”€β”€ neon-button/
β”‚   β”œβ”€β”€ component.tsx
β”‚   └── meta.json          ← name, tags, description, timestamps
β”œβ”€β”€ gradient-hero/
β”‚   β”œβ”€β”€ component.tsx
β”‚   └── meta.json
└── .collect-ui-index.json
```

<div align="center">

| βœ… Human-readable | βœ… Git-friendly | βœ… No database | βœ… Yours forever |
|:---:|:---:|:---:|:---:|

</div>

---

## βš™οΈ Configuration

| Env var | Default | Description |
|:--------|:--------|:------------|
| `COLLECT_UI_DIR` | `./.ui-library` | Where components are stored |
| `COLLECT_UI_INDEX` | `.collect-ui-index.json` | Index filename |
| `COLLECT_UI_LOG` | `info` | Log level β€” `debug` Β· `info` Β· `warn` Β· `error` |

---

## πŸ§ͺ Development

```bash
# Clone
git clone https://github.com/<your-username>/collect-ui-mcp.git
cd collect-ui-mcp

# Install & build
npm install
npm run build

# Watch mode
npm run dev

# Test
npm test
```

### πŸ”¬ Debug with the MCP Inspector

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

---

## πŸ—ΊοΈ Roadmap

- [ ] ☁️ Cloud sync β€” S3 / WebDAV
- [ ] πŸ–ΌοΈ Image & screenshot attachments
- [ ] 🧠 Framework-aware imports
- [ ] 🎨 Figma plugin bridge
- [ ] πŸ“Š Web dashboard

> πŸ’‘ Have an idea? [Open an issue](https://github.com/<your-username>/collect-ui-mcp/issues) β€” PRs are welcome!

---

## 🀝 Contributing

<div align="center">

**Every contribution counts β€” bugs, docs, ideas, code.**

</div>

```bash
# 1. Fork the repo, then:
git checkout -b feat/my-feature
git commit -m "feat: add my feature"
git push origin feat/my-feature
# 2. Open a Pull Request πŸš€
```

Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) before getting started.

---

## πŸ™ Acknowledgements

- 🧬 **[Model Context Protocol](https://modelcontextprotocol.io)** β€” the spec that makes this possible
- 🏒 **[Anthropic](https://anthropic.com)** β€” for building and open-sourcing MCP
- 🫑 Everyone who has a folder called `snippets-final-v3-USE-THIS-ONE`

---

## πŸ“„ License

<div align="center">

**[MIT](LICENSE)** Β© `<Your Name>`

<br/>

⭐ **If this saved you a bookmark, star the repo!**

<sub>Made with ❀️ and a mild obsession with clean components.</sub>

</div>
>>>>>>> 6995874 (Initial commit)