MCP CopyQ Server

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-copyq

Claude 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/архив")

______________________________________________________________________

设计原则

1. 最小工具 -3代替10+
2. 无状态 每个挑战都是独立的。
3. 紧凑的答案 -管道隔离，无多余字段
4. 烧蚀 -大数据的skip/max_items
5. 显式参数 — include_text 代替 fields: "minimal"
6. 预览模式 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

______________________________________________________________________

许可证

麻省理工学院