Metadata-Version: 2.4
Name: keyword-labeler
Version: 1.0.3
Summary: SEO keyword grouping plugin for Claude Desktop — tự động phân nhóm keyword bằng Claude Batch API
Project-URL: Homepage, https://github.com/minhdo01011990-glitch/keyword-labeler
Project-URL: Repository, https://github.com/minhdo01011990-glitch/keyword-labeler
Project-URL: Issues, https://github.com/minhdo01011990-glitch/keyword-labeler/issues
Author: minhdo01011990-glitch
License: MIT License
        
        Copyright (c) 2026 minhdo01011990-glitch
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: claude,keyword,mcp,nlp,seo,vietnamese
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Requires-Dist: anthropic>=0.40.0
Requires-Dist: mcp[cli]<2.0.0,>=1.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.0.0
Description-Content-Type: text/markdown

# Keyword Labeler

**Plugin Claude Desktop / Claude Code** để tự động phân nhóm keyword SEO từ file Excel/CSV (lên đến 10.000 keyword).

> **English summary:** An MCP plugin for Claude Desktop and Claude Code that automatically clusters SEO keywords using Claude Batch API. Input: Excel/CSV with keyword + volume columns. Output: Excel (3 sheets: Labeled / Removed / Summary) or Markdown. Supports SpySERP URL-overlap pre-grouping, brand keyword handling, and Vietnamese no-diacritic filtering.

---

## Tính năng

- **Phân nhóm tự động** theo format `chủ đề - hậu tố 1 - hậu tố 2` (ví dụ: `viêm phụ khoa - dấu hiệu - khi mang thai`)
- **Claude Batch API** — tiết kiệm 50% chi phí so với standard API
- **Vocabulary nhất quán** — Phase 5a build vocabulary cố định, inject vào tất cả batch
- **Merge pass** — gộp tên nhóm trùng nghĩa sau khi phân nhóm
- **SpySERP integration** — pre-group theo URL overlap (≥5 URL chung)
- **Xử lý brand keyword** — 4 chế độ: nhóm riêng / gộp / loại bỏ / giữ nguyên
- **Lọc keyword** — loại sai chính tả, không dấu volume thấp, off-topic
- **Review UI** — xem, merge, rename nhóm ngay trong Claude trước khi export
- **Export** — Excel 3 sheet hoặc Markdown

---

## Yêu cầu

- Python 3.9+
- [Claude Desktop](https://claude.ai/download) hoặc Claude Code
- `ANTHROPIC_API_KEY` trong environment (hoặc file `~/.anthropic_key`)

---

## Cài đặt

### Bước 1 — Chạy 1 lệnh terminal

```bash
bash <(curl -sSL https://raw.githubusercontent.com/minhdo01011990-glitch/keyword-labeler/main/install.sh)
```

Script tự động:
1. Phát hiện Python 3.9+ và cài `keyword-labeler` từ PyPI
2. Cấu hình MCP server vào `claude_desktop_config.json` (Claude Desktop)
3. Cấu hình MCP server vào `~/.claude/settings.json` (Claude Code CLI)
4. Cài SKILL.md vào `~/.claude/skills/keyword/` để kích hoạt lệnh `/keyword`
5. Restart Claude Desktop (macOS)

### Bước 2 — Upload plugin vào Claude Desktop (1 lần duy nhất)

1. Tải file [`keyword-labeler.plugin`](https://github.com/minhdo01011990-glitch/keyword-labeler/releases/latest) từ trang Releases
2. Mở Claude Desktop → **Cowork → Settings → Plugins → Upload** → chọn file vừa tải

Sau bước này, gõ `/keyword` trong Cowork là dùng được.

> **Claude Code CLI**: không cần bước này — lệnh `/keyword` hoạt động ngay sau Bước 1.

---

## API Key

Khi gõ `/keyword` lần đầu, plugin tự kiểm tra API key. Nếu chưa có, Claude sẽ hỏi và lưu lại tự động.

Hoặc set thủ công:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."   # thêm vào ~/.zshrc hoặc ~/.bashrc
```

---

## Cập nhật lên phiên bản mới

### Bước 1 — Cập nhật MCP server

```bash
bash <(curl -sSL https://raw.githubusercontent.com/minhdo01011990-glitch/keyword-labeler/main/install.sh)
```

### Bước 2 — Cập nhật plugin Cowork

*(Chỉ cần khi SKILL.md thay đổi — xem Release Notes để biết)*

1. Tải `keyword-labeler.plugin` mới từ [Releases](https://github.com/minhdo01011990-glitch/keyword-labeler/releases/latest)
2. Cowork → Settings → Plugins → **xóa plugin cũ** → **Upload** file mới

---

## Sử dụng

1. Mở Claude Desktop, gõ `/keyword`
2. Điền form:
   - **Chủ đề SEO** (ví dụ: `sữa bột cho trẻ em`)
   - **Đường dẫn file keyword** (Excel/CSV: cột `keyword` + `volume`)
   - **File SpySERP** (tuỳ chọn)
   - **Xử lý brand**: [1] nhóm riêng / [2] gộp / [3] loại bỏ / [4] giữ nguyên
   - **Ngưỡng volume không dấu** (default: 100)
   - **Output**: Excel hoặc Markdown
3. Xác nhận chi phí ước tính → plugin chạy tự động
4. Review nhóm, merge/rename nếu cần → export

### Format file keyword

| keyword | volume |
|---------|--------|
| sữa bột enfamil | 2400 |
| cách chọn sữa cho bé | 880 |
| sữa bột loại nào tốt | 590 |

### Format output Excel

**Sheet Labeled**: Keyword, Volume, Nhóm, Chủ đề, Hậu tố 1, Hậu tố 2, Intent, Thương hiệu  
**Sheet Removed**: Keyword, Volume, Lý do lọc  
**Sheet Summary**: Nhóm, Số keyword, Tổng volume, Informational, Commercial, Transactional, Navigational

---

## Kiến trúc

```
/keyword (Claude Desktop prompt)
  → data_loader      — đọc Excel/CSV, dedup volume
  → brand_detector   — tag branded keyword
  → filter           — Batch API: lọc sai chính tả, off-topic
  → spyserp_grouper  — URL overlap pre-group (≥5 URL)
  → grouper          — Phase 5a vocab + Phase 5b Batch API
  → merge_pass       — gộp tên nhóm trùng nghĩa
  → review UI        — xem / merge / rename trong Claude
  → exporter         — Excel 3 sheet hoặc Markdown
```

**Stack:** Python + [FastMCP](https://github.com/modelcontextprotocol/python-sdk) + [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-python) + openpyxl + pandas

---

## Chi phí ước tính

Với 1.000 keyword (chủ đề tiếng Việt):
- Filter (Haiku Batch): ~$0.01
- Grouper (Sonnet Batch): ~$0.14
- **Tổng: ~$0.15**

Batch API tự động tiết kiệm 50% so với standard API. Thời gian xử lý: 15–40 phút tùy số lượng keyword.

---

## License

MIT — xem [LICENSE](LICENSE).
