MCP CopyQ服务器
MCP服务器,用于将Copyq(剪贴板管理器)与LLM代理集成。
概念
copyq中的数据结构```
mcp/
├── info/ # 🔒 только элементы (без подвкладок)
├── заметки/ # 🔒 только элементы (без подвкладок)
└── workspace/ # ✅ элементы + подвкладки
### 元素(item)
每个元素包含:
- **文本** -正文
- **标签** -标记(字符串数组)
- **笔记** -文本注释
______________________________________________________________________
## 工具(3件)
### 1. `mcp_read`
通用数据读取。
#### 参数
≫参数≫类型≫默认≫描述≫
`mode` · `"tree"` / `"list"` / `"item"` / `"search"` · — · **强制性的**
`tab` · 字符串 · `""` 路径: `"info"`, `"workspace/proj1"`
`index` · number · --Для模式=项目
`query` · string · Для模式=搜索(正则表达式)
`search_in` · `"text"` / `"note"` / `"tags"` / `"all"` · `"all"` 在哪里寻找
| `max_depth` ≫number=2≫树最大值。深度。
| `max_items` 第20章有限元素
| `skip` ÐÐÐÐÐÐÐÐÐÐÐÐÐ
| `include_text` ÐboolÐtrueÐÐÐÐÐÐÐÐÐÐ
| `include_tags` ÐÐÐÐÐÐÐÐÐÐÐÐ
| `include_note` ÐÐÐÐÐÐÐÐÐÐÐÐ
#### 模式(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` 未知模式
#### 引擎盖下(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
通用数据记录。
参数
≫参数≫类型≫默认≫描述≫
mode · string · 强制性的 (见下文)。
| tab ≫string≫标签路径≫
| index #Number––对于Item操作。
| text Ðstring––文本(用于添加/更新)→
| tags string[]标签
note · string · — · 注释
field · "text" / "note" / "tags" 要更新,要改变什么。
edit_mode · "replace" / "append" / "prepend" / "substitute" · "replace" 如何改变
| match ≫字符串––Substitute-替换––替换––替换
| to_tab ≫string≫for move-移动到哪里≫
path · string · Дляtab_create/tab_delete
intent · "execute" / "preview" · "execute" 执行或显示效果。
模式(Mode)
≫模式≫级别≫描述≫必需参数≫
| add ÐitemÐÐÐÐÐÐÐÐÐÐÐÐ
| update ÐitemÐÐÐÐÐÐÐÐÐÐÐÐÐÐ
| delete ÐitemÐÐÐÐÐÐÐÐÐÐÐ
| move ÐitemÐÐÐÐÐÐÐÐÐÐÐÐÐ
tab_create (仅限工作空间/)
tab_delete ÐcollectionÐÐÐÐÐÐÐÐÐÐÐÐ)
编辑模式更新
ÐÐÐÐÐÐÐÐÐÐÐÐÐ
文本/注释 · replace 完全替代。
文本/注释 · append 写到最后。
文本/注释 · prepend 先写完。
文本/注释 · substitute 更换 match → text/note
标签 · replace 更换所有标签
标签 · append 添加标签(保存旧的)
标签 · remove 删除指定的标签
意图:预览
当 intent="preview" -不执行操作,而是返回将发生的事情:```
action: delete
target: mcp/info[3]
will_remove: "Текст который удалится..." | [метки] | +note
#### 可能的错误
代码描述
| `TAB_NOT_FOUND` 标签不存在。
| `INDEX_OUT_OF_BOUNDS` 指数在外
`PERMISSION_DENIED` · tab_create/tab_delete工作区
| `INVALID_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"]
______________________________________________________________________
## 访问权限
≫操作≫信息≫笔记≫工作空间≫
Read(所有模式)✅ · ✅ · ✅
添加 · ✅ · ✅ · ✅
更新 · ✅ · ✅ · ✅
删除 · ✅ · ✅ · ✅
移动 · ✅ · ✅ · ✅
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/архив")
设计原则
- 最小工具 -3代替10+
- 无状态 每个挑战都是独立的。
- 紧凑的答案 -管道隔离,无多余字段
- 烧蚀 -大数据的skip/max_items
- 显式参数 —
include_text代替fields: "minimal" - 预览模式 intent=“preview”用于危险操作
- 明确的错误 代码 + 描述
项目结构```
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
```
许可证
麻省理工学院
