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）
# 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）
# 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 |❌ | ❌ | ✅ |
______________________________________________________________________
安装
# Требования
# - 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-copyqClaude Desktop配置
{
"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______________________________________________________________________
许可证
麻省理工学院