MCP CopyQ Server

Instructions

Implementation Reference

• src/mcp_copyq/tools/write.py:23-88 (handler)

  Main handler function for the mcp_write tool. Validates input mode and dispatches to specialized helper functions based on the operation mode (add, update, delete, move, tab_create, tab_delete). Supports preview mode.
  async def mcp_write( mode: str, tab: str | None = None, index: int | None = None, text: str | None = None, tags: list[str] | None = None, note: str | None = None, field: str | None = None, edit_mode: str = "replace", match: str | None = None, to_tab: str | None = None, path: str | None = None, intent: str = "execute", ) -> str: """ Universal write operation for CopyQ MCP. Modes: - add: Add new item to tab - update: Update existing item - delete: Delete item - move: Move item to another tab - tab_create: Create new subtab (workspace only) - tab_delete: Delete subtab (workspace only) intent: - execute: Perform the operation - preview: Show what would happen without executing Returns compact pipe-separated format. """ try: # Validate mode valid_modes = [m.value for m in WriteMode] if mode not in valid_modes: raise InvalidModeError(mode, valid_modes) is_preview = intent == "preview" if mode == "add": return await _write_add(tab, text, tags, note, is_preview) elif mode == "update": return await _write_update( tab, index, field, edit_mode, text, tags, note, match, is_preview ) elif mode == "delete": return await _write_delete(tab, index, is_preview) elif mode == "move": return await _write_move(tab, index, to_tab, is_preview) elif mode == "tab_create": return await _write_tab_create(path, is_preview) elif mode == "tab_delete": return await _write_tab_delete(path, is_preview) return "error|INVALID_MODE|Unknown mode" except MCPCopyQError as e: return e.to_response() except Exception as e: return f"error|INTERNAL|{str(e)}"
• src/mcp_copyq/server.py:118-199 (registration)

  MCP tool registration for mcp_write, including name, detailed description, and JSON inputSchema defining parameters, enums, and validation rules.
  Tool( name="mcp_write", description="""Write to CopyQ clipboard manager. IMPORTANT: All data stored under "mcp/" prefix. When you use tab="info", actual CopyQ path is "mcp/info". Available tabs: - info - general storage (use tab="info") - заметки - notes (use tab="заметки") - workspace - projects, supports subtabs (use tab="workspace" or "workspace/myproject") Modes: - add: Add item to tab. Params: tab, text, tags (optional), note (optional) - update: Update item. Params: tab, index, field, text/tags/note - delete: Delete item. Params: tab, index - move: Move item. Params: tab, index, to_tab - tab_create: Create subtab in workspace only. Params: path (e.g. "workspace/newproject") - tab_delete: Delete subtab. Params: path Response shows full_path (e.g. "mcp/info") confirming where data was written. Errors: TAB_NOT_FOUND, INDEX_OUT_OF_BOUNDS, PERMISSION_DENIED, MISSING_PARAM""", inputSchema={ "type": "object", "properties": { "mode": { "type": "string", "enum": ["add", "update", "delete", "move", "tab_create", "tab_delete"], "description": "Operation mode" }, "tab": { "type": "string", "description": "Tab path" }, "index": { "type": "integer", "description": "Item index" }, "text": { "type": "string", "description": "Text content" }, "tags": { "type": "array", "items": {"type": "string"}, "description": "Tags list" }, "note": { "type": "string", "description": "Note content" }, "field": { "type": "string", "enum": ["text", "note", "tags"], "description": "Field to update" }, "edit_mode": { "type": "string", "enum": ["replace", "append", "prepend", "substitute", "remove"], "default": "replace" }, "match": { "type": "string", "description": "String to match (for substitute)" }, "to_tab": { "type": "string", "description": "Destination tab (for move)" }, "path": { "type": "string", "description": "Tab path (for tab_create/tab_delete)" }, "intent": { "type": "string", "enum": ["execute", "preview"], "default": "execute" } }, "required": ["mode"] } ),
• src/mcp_copyq/models.py:78-93 (schema)

  Pydantic model and enums (WriteMode, EditMode, FieldType, Intent) defining structured input validation for mcp_write parameters.
  class WriteRequest(BaseModel): """Parameters for mcp_write tool.""" mode: WriteMode = Field(..., description="Operation mode") tab: str | None = Field(default=None, description="Tab path") index: int | None = Field(default=None, description="Item index") text: str | None = Field(default=None, description="Text content") tags: list[str] | None = Field(default=None, description="Tags list") note: str | None = Field(default=None, description="Note content") field: FieldType | None = Field(default=None, description="Field to update") edit_mode: EditMode = Field(default=EditMode.REPLACE, description="How to edit") match: str | None = Field(default=None, description="String to match (for substitute)") to_tab: str | None = Field(default=None, description="Destination tab (for move)") path: str | None = Field(default=None, description="Tab path (for tab_create/tab_delete)") intent: Intent = Field(default=Intent.EXECUTE, description="Execute or preview")
• src/mcp_copyq/tools/validate.py:97-211 (helper)

  Helper function for validating mcp_write parameters without execution, used by the mcp_validate tool. Checks modes, required params, tab/index existence, permissions.
  async def _validate_write(params: dict) -> tuple[list[str], list[str]]: """Validate mcp_write parameters.""" errors: list[str] = [] warnings: list[str] = [] mode = params.get("mode") tab = params.get("tab") index = params.get("index") text = params.get("text") tags = params.get("tags") note = params.get("note") field = params.get("field") edit_mode = params.get("edit_mode", "replace") match = params.get("match") to_tab = params.get("to_tab") path = params.get("path") intent = params.get("intent", "execute") # Validate mode valid_modes = [m.value for m in WriteMode] if not mode: errors.append("MISSING_PARAM: mode is required") elif mode not in valid_modes: errors.append(f"INVALID_MODE: '{mode}' not in {valid_modes}") return errors, warnings # Validate intent if intent not in [i.value for i in Intent]: errors.append(f"INVALID_PARAM: intent '{intent}' invalid") # Mode-specific validation if mode == "add": if not tab: errors.append("MISSING_PARAM: tab required for mode=add") if not text: errors.append("MISSING_PARAM: text required for mode=add") if tab: root = tab.split("/")[0] if root not in ALLOWED_ROOT_TABS: errors.append(f"TAB_NOT_FOUND: root '{root}' not allowed") elif mode == "update": if not tab: errors.append("MISSING_PARAM: tab required for mode=update") if index is None: errors.append("MISSING_PARAM: index required for mode=update") if not field: errors.append("MISSING_PARAM: field required for mode=update") elif field not in [f.value for f in FieldType]: errors.append(f"INVALID_PARAM: field '{field}' invalid") if edit_mode not in [e.value for e in EditMode]: errors.append(f"INVALID_PARAM: edit_mode '{edit_mode}' invalid") if edit_mode == "substitute" and not match: errors.append("MISSING_PARAM: match required for edit_mode=substitute") # Check field/value match if field == "text" and text is None: errors.append("MISSING_PARAM: text required for field=text") if field == "tags" and tags is None: errors.append("MISSING_PARAM: tags required for field=tags") if field == "note" and note is None: errors.append("MISSING_PARAM: note required for field=note") # Check tab and index exist if tab and index is not None: if not await client.tab_exists(tab): errors.append(f"TAB_NOT_FOUND: {tab}") else: count = await client.get_count(tab) if index < 0 or index >= count: errors.append(f"INDEX_OUT_OF_BOUNDS: {index} (count: {count})") elif mode == "delete": if not tab: errors.append("MISSING_PARAM: tab required for mode=delete") if index is None: errors.append("MISSING_PARAM: index required for mode=delete") if tab and index is not None: if not await client.tab_exists(tab): errors.append(f"TAB_NOT_FOUND: {tab}") else: count = await client.get_count(tab) if index < 0 or index >= count: errors.append(f"INDEX_OUT_OF_BOUNDS: {index} (count: {count})") elif mode == "move": if not tab: errors.append("MISSING_PARAM: tab required for mode=move") if index is None: errors.append("MISSING_PARAM: index required for mode=move") if not to_tab: errors.append("MISSING_PARAM: to_tab required for mode=move") if tab and not await client.tab_exists(tab): errors.append(f"TAB_NOT_FOUND: {tab}") elif mode == "tab_create": if not path: errors.append("MISSING_PARAM: path required for mode=tab_create") elif not path.startswith("workspace"): errors.append(f"PERMISSION_DENIED: tab_create only allowed in workspace/") if path and await client.tab_exists(path): warnings.append(f"Tab already exists: {path}") elif mode == "tab_delete": if not path: errors.append("MISSING_PARAM: path required for mode=tab_delete") elif not path.startswith("workspace"): errors.append(f"PERMISSION_DENIED: tab_delete only allowed in workspace/") if path and not await client.tab_exists(path): errors.append(f"TAB_NOT_FOUND: {path}") return errors, warnings
• src/mcp_copyq/tools/write.py:98-137 (helper)

  Example helper function for 'add' mode: validates params, generates preview if requested, adds item via CopyQ client, returns formatted response.
  async def _write_add( tab: str | None, text: str | None, tags: list[str] | None, note: str | None, is_preview: bool, ) -> str: """Add new item to tab.""" if not tab: raise MissingParamError("tab", "add") if not text: raise MissingParamError("text", "add") # Check tab exists (will be created if not) if not await client.tab_exists(tab): # Auto-create only for existing root tabs root = tab.split("/")[0] if root not in ALLOWED_ROOT_TABS: raise TabNotFoundError(tab) if is_preview: text_preview = text[:PREVIEW_LENGTH] + "..." if len(text) > PREVIEW_LENGTH else text tags_str = f"[{','.join(tags)}]" if tags else "[]" note_preview = (note[:50] + "...") if note and len(note) > 50 else (note or "") return ( f"preview|mode:add\n" f"tab:{tab}\n" f"will_add:\n" f" text:\"{text_preview}\"\n" f" tags:{tags_str}\n" f" note:\"{note_preview}\"" ) new_index = await client.add_item(tab, text, tags, note) return ( f"ok|mode:add|tab:{tab}|full_path:{MCP_ROOT}/{tab}|index:{new_index}|" f"text_len:{len(text)}|tags:{len(tags) if tags else 0}|note:{bool(note)}" )