README.md•11.4 kB
# MCP CopyQ Server
MCP-сервер для интеграции CopyQ (менеджер буфера обмена) с LLM-агентами.
## Концепция
### Структура данных в CopyQ
```
mcp/
├── info/ # 🔒 только элементы (без подвкладок)
├── заметки/ # 🔒 только элементы (без подвкладок)
└── workspace/ # ✅ элементы + подвкладки
```
### Элемент (Item)
Каждый элемент содержит:
- **text** — основной текст
- **tags** — метки (массив строк)
- **note** — заметка к тексту
---
## Инструменты (3 шт.)
### 1. `mcp_read`
Универсальное чтение данных.
#### Параметры
| Параметр | Тип | Default | Описание |
|----------|-----|---------|----------|
| `mode` | `"tree"` / `"list"` / `"item"` / `"search"` | — | **обязательный** |
| `tab` | string | `""` | Путь: `"info"`, `"workspace/proj1"` |
| `index` | number | — | Для mode=item |
| `query` | string | — | Для mode=search (regex) |
| `search_in` | `"text"` / `"note"` / `"tags"` / `"all"` | `"all"` | Где искать |
| `max_depth` | number | 2 | Для tree — макс. глубина |
| `max_items` | number | 20 | Лимит элементов |
| `skip` | number | 0 | Пагинация — пропустить N |
| `include_text` | bool | true | Включить текст/превью |
| `include_tags` | bool | true | Включить метки |
| `include_note` | bool | false | Включить заметку |
#### Режимы (mode)
**`tree`** — структура вкладок с метаданными
```
mcp/info [5]
0: "Инструкция по API..." [api,docs]
1: "Конфиг сервера..." [config]
mcp/workspace [3]
└─ mcp/workspace/проект1 [12]
```
**`list`** — элементы конкретной вкладки
```
mode:list|tab:info|total:47|showing:0-19
0|"Инструкция по API..."|[api,docs]|+note
1|"Конфиг сервера..."|[config]|
```
**`item`** — один элемент полностью
**`search`** — поиск по содержимому
#### Возможные ошибки
| Код | Описание |
|-----|----------|
| `TAB_NOT_FOUND` | Вкладка не существует |
| `INDEX_OUT_OF_BOUNDS` | Индекс за пределами |
| `INVALID_MODE` | Неизвестный mode |
#### Под капотом (CopyQ CLI)
```bash
# tree
copyq tab | grep "^mcp/"
copyq tab "mcp/..." count
copyq tab "mcp/..." read 0 | head -c 50
# list
copyq tab "mcp/${tab}" count
copyq tab "mcp/${tab}" read $i
copyq tab "mcp/${tab}" read "application/x-copyq-tags" $i
# item
copyq tab "mcp/${tab}" read ${index}
copyq tab "mcp/${tab}" read "application/x-copyq-tags" ${index}
copyq tab "mcp/${tab}" read "application/x-copyq-item-notes" ${index}
# search
copyq eval "/* JS: grep по tabs */"
```
---
### 2. `mcp_write`
Универсальная запись данных.
#### Параметры
| Параметр | Тип | Default | Описание |
|----------|-----|---------|----------|
| `mode` | string | — | **обязательный** (см. ниже) |
| `tab` | string | — | Путь вкладки |
| `index` | number | — | Для item-операций |
| `text` | string | — | Текст (для add/update) |
| `tags` | string[] | — | Метки |
| `note` | string | — | Заметка |
| `field` | `"text"` / `"note"` / `"tags"` | — | Для update — что менять |
| `edit_mode` | `"replace"` / `"append"` / `"prepend"` / `"substitute"` | `"replace"` | Как менять |
| `match` | string | — | Для substitute — что заменить |
| `to_tab` | string | — | Для move — куда переместить |
| `path` | string | — | Для tab_create/tab_delete |
| `intent` | `"execute"` / `"preview"` | `"execute"` | Выполнить или показать эффект |
#### Режимы (mode)
| mode | Уровень | Описание | Обязательные параметры |
|------|---------|----------|------------------------|
| `add` | item | Добавить элемент в начало | tab, text |
| `update` | item | Изменить элемент | tab, index, field, (text/tags/note) |
| `delete` | item | Удалить элемент | tab, index |
| `move` | item | Переместить в другую вкладку | tab, index, to_tab |
| `tab_create` | collection | Создать подвкладку | path (только workspace/*) |
| `tab_delete` | collection | Удалить подвкладку | path (только workspace/*) |
#### edit_mode для update
| field | edit_mode | Действие |
|-------|-----------|----------|
| text/note | `replace` | Полная замена |
| text/note | `append` | Дописать в конец |
| text/note | `prepend` | Дописать в начало |
| text/note | `substitute` | Заменить `match` → `text`/`note` |
| tags | `replace` | Заменить все метки |
| tags | `append` | Добавить метки (сохранив старые) |
| tags | `remove` | Удалить указанные метки |
#### intent: preview
При `intent="preview"` — не выполняет действие, а возвращает что произойдёт:
```
action: delete
target: mcp/info[3]
will_remove: "Текст который удалится..." | [метки] | +note
```
#### Возможные ошибки
| Код | Описание |
|-----|----------|
| `TAB_NOT_FOUND` | Вкладка не существует |
| `INDEX_OUT_OF_BOUNDS` | Индекс за пределами |
| `PERMISSION_DENIED` | tab_create/tab_delete вне workspace |
| `INVALID_MODE` | Неизвестный mode |
| `MISSING_PARAM` | Не хватает обязательного параметра |
| `MATCH_NOT_FOUND` | substitute: match не найден в тексте |
#### Формат ответа
```
ok|mode:add|tab:info|index:0|text_len:156|tags:2
```
#### Под капотом (CopyQ CLI)
```bash
# add
copyq tab "mcp/${tab}" write 0 \
"text/plain" "${text}" \
"application/x-copyq-tags" "${tags}" \
"application/x-copyq-item-notes" "${note}"
# update (substitute)
OLD=$(copyq tab "mcp/${tab}" read ${index})
NEW=$(echo "$OLD" | sed "s/${match}/${value}/g")
TAGS=$(copyq tab "mcp/${tab}" read "application/x-copyq-tags" ${index})
NOTE=$(copyq tab "mcp/${tab}" read "application/x-copyq-item-notes" ${index})
copyq tab "mcp/${tab}" write ${index} \
"text/plain" "$NEW" \
"application/x-copyq-tags" "$TAGS" \
"application/x-copyq-item-notes" "$NOTE"
# delete
copyq tab "mcp/${tab}" remove ${index}
# move
# read all → write to to_tab → remove from tab
# tab_create
copyq tab "mcp/${path}"
# tab_delete
copyq removeTab "mcp/${path}"
```
---
### 3. `mcp_validate`
Проверить корректность вызова без выполнения.
#### Параметры
| Параметр | Тип | Описание |
|----------|-----|----------|
| `tool` | `"read"` / `"write"` | Какой инструмент проверить |
| `params` | object | Параметры вызова |
#### Формат ответа
Успех:
```
valid: true | warnings: [] | estimated_tokens: 340
```
Ошибка:
```
valid: false | errors: ["TAB_NOT_FOUND: workspace/xxx"]
```
---
## Права доступа
| Операция | info | заметки | workspace |
|----------|:----:|:-------:|:---------:|
| read (все режимы) | ✅ | ✅ | ✅ |
| add | ✅ | ✅ | ✅ |
| update | ✅ | ✅ | ✅ |
| delete | ✅ | ✅ | ✅ |
| move | ✅ | ✅ | ✅ |
| tab_create | ❌ | ❌ | ✅ |
| tab_delete | ❌ | ❌ | ✅ |
---
## Установка
```bash
# Требования
# - Python 3.11+
# - CopyQ установлен и запущен
# - Путь к CopyQ: C:\Program Files\CopyQ\copyq.exe
# Установка
cd C:\sts\projects\mcp-copyq
uv venv
uv pip install -e .
# Запуск
uv run mcp-copyq
```
## Конфигурация Claude Desktop
```json
{
"mcpServers": {
"copyq": {
"command": "uv",
"args": ["--directory", "C:\\sts\\projects\\mcp-copyq", "run", "mcp-copyq"]
}
}
}
```
---
## Примеры использования
### Получить структуру
```
mcp_read(mode="tree", max_depth=2, max_items=5)
```
### Список элементов вкладки
```
mcp_read(mode="list", tab="info", max_items=10, include_note=true)
```
### Прочитать элемент
```
mcp_read(mode="item", tab="info", index=0)
```
### Поиск
```
mcp_read(mode="search", query="API", search_in="all", max_items=10)
```
### Добавить элемент
```
mcp_write(mode="add", tab="info", text="Новая запись", tags=["important"])
```
### Изменить текст (дописать в конец)
```
mcp_write(mode="update", tab="info", index=0, field="text", edit_mode="append", text="\n\nДополнение")
```
### Заменить фрагмент
```
mcp_write(mode="update", tab="info", index=0, field="text", edit_mode="substitute", match="старое", text="новое")
```
### Добавить метку (сохранив существующие)
```
mcp_write(mode="update", tab="info", index=0, field="tags", edit_mode="append", tags=["urgent"])
```
### Удалить с превью
```
mcp_write(mode="delete", tab="info", index=0, intent="preview")
mcp_write(mode="delete", tab="info", index=0, intent="execute")
```
### Создать подвкладку
```
mcp_write(mode="tab_create", path="workspace/новый_проект")
```
### Переместить элемент
```
mcp_write(mode="move", tab="info", index=0, to_tab="workspace/архив")
```
---
## Принципы дизайна
1. **Минимум инструментов** — 3 вместо 10+
2. **Stateless** — каждый вызов независим
3. **Компактные ответы** — pipe-separated, без лишних полей
4. **Пагинация** — skip/max_items для больших данных
5. **Явные параметры** — `include_text` вместо `fields: "minimal"`
6. **Preview mode** — intent="preview" для опасных операций
7. **Чёткие ошибки** — коды + описания
---
## Структура проекта
```
mcp-copyq/
├── README.md
├── pyproject.toml
├── src/
│ └── mcp_copyq/
│ ├── __init__.py
│ ├── server.py # MCP server
│ ├── copyq_client.py # CopyQ CLI wrapper
│ ├── tools/
│ │ ├── __init__.py
│ │ ├── read.py # mcp_read
│ │ ├── write.py # mcp_write
│ │ └── validate.py # mcp_validate
│ ├── models.py # Pydantic models
│ └── errors.py # Error codes
└── tests/
├── __init__.py
├── test_read.py
├── test_write.py
├── test_validate.py
└── test_integration.py
```
---
## Лицензия
MIT