MCP CopyQ Server

Instructions

Implementation Reference

• src/mcp_copyq/tools/read.py:22-93 (handler)

  Main handler function for the mcp_read tool. Validates parameters and dispatches to mode-specific helper functions (_read_tree, _read_list, _read_item, _read_search).

  async def mcp_read(
      mode: str,
      tab: str = "",
      index: int | None = None,
      query: str | None = None,
      search_in: str = "all",
      scope: str = "mcp",
      max_depth: int = 2,
      max_items: int = 20,
      skip: int = 0,
      include_text: bool = True,
      include_tags: bool = True,
      include_note: bool = False,
  ) -> str:
      """
      Universal read operation for CopyQ MCP.
  
      Modes:
      - tree: Get tab structure with metadata
      - list: Get items from a specific tab
      - item: Get single item fully
      - search: Search across tabs
  
      Scope:
      - mcp: Only mcp/* tabs (default, full access)
      - all: All CopyQ tabs (external tabs are read-only)
      - external: Only non-mcp tabs (read-only)
  
      Returns compact pipe-separated format.
      """
      try:
          # Validate mode
          valid_modes = [m.value for m in ReadMode]
          if mode not in valid_modes:
              raise InvalidModeError(mode, valid_modes)
  
          # Validate scope
          valid_scopes = [s.value for s in Scope]
          if scope not in valid_scopes:
              raise MCPCopyQError(ErrorCode.INVALID_PARAM, f"Invalid scope '{scope}'. Valid: {', '.join(valid_scopes)}")
  
          if mode == "tree":
              return await _read_tree(max_depth, max_items, include_text, include_tags, scope)
  
          elif mode == "list":
              if not tab:
                  raise MissingParamError("tab", mode)
              return await _read_list(
                  tab, max_items, skip, include_text, include_tags, include_note, scope
              )
  
          elif mode == "item":
              if not tab:
                  raise MissingParamError("tab", mode)
              if index is None:
                  raise MissingParamError("index", mode)
              return await _read_item(tab, index, include_text, include_tags, include_note, scope)
  
          elif mode == "search":
              if not query:
                  raise MissingParamError("query", mode)
              return await _read_search(
                  query, search_in, max_items, skip, include_text, include_tags, scope
              )
  
          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:21-117 (registration)

  Tool registration in @server.list_tools(), defining name, description, and JSON inputSchema for mcp_read.

          Tool(
              name="mcp_read",
              description="""Read from CopyQ clipboard manager.
  
  MCP tabs (full read/write access):
  - mcp/info - general information storage
  - mcp/заметки - notes storage
  - mcp/workspace - projects (supports subtabs like workspace/myproject)
  
  External tabs (READ-ONLY access with scope="all" or scope="external"):
  - All other CopyQ tabs like "&clipboard", personal tabs, etc.
  - Use scope="all" to see all tabs, scope="external" for non-mcp only
  
  Modes:
  - tree: Get tab structure with previews. Use FIRST to see available tabs.
  - list: Get items from tab with pagination
  - item: Get single item with full content (text, tags, note)
  - search: Search by regex across tabs
  
  Parameters:
  - mode (required): "tree" | "list" | "item" | "search"
  - tab: For mcp tabs use relative path "info", "workspace/proj1". For external use full name "&clipboard"
  - scope: "mcp" (default) | "all" | "external" - controls which tabs are accessible
  - index: Item index (for mode=item)
  - query: Search regex (for mode=search)
  
  Examples:
  - tree of mcp tabs: mode="tree"
  - tree of ALL tabs: mode="tree", scope="all"
  - read external tab: mode="list", tab="&clipboard", scope="external"
  - search everywhere: mode="search", query="pattern", scope="all"
  
  Errors: TAB_NOT_FOUND, INDEX_OUT_OF_BOUNDS, INVALID_MODE""",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "mode": {
                          "type": "string",
                          "enum": ["tree", "list", "item", "search"],
                          "description": "Operation mode"
                      },
                      "tab": {
                          "type": "string",
                          "description": "Tab path: 'info', 'workspace/proj1' or full external name '&clipboard'"
                      },
                      "scope": {
                          "type": "string",
                          "enum": ["mcp", "all", "external"],
                          "default": "mcp",
                          "description": "Tab scope: mcp (default, read/write), all (read external), external (only non-mcp, read-only)"
                      },
                      "index": {
                          "type": "integer",
                          "description": "Item index (for mode=item)"
                      },
                      "query": {
                          "type": "string",
                          "description": "Search regex (for mode=search)"
                      },
                      "search_in": {
                          "type": "string",
                          "enum": ["text", "note", "tags", "all"],
                          "default": "all"
                      },
                      "max_depth": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 10,
                          "default": 2
                      },
                      "max_items": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 100,
                          "default": 20
                      },
                      "skip": {
                          "type": "integer",
                          "minimum": 0,
                          "default": 0
                      },
                      "include_text": {
                          "type": "boolean",
                          "default": True
                      },
                      "include_tags": {
                          "type": "boolean",
                          "default": True
                      },
                      "include_note": {
                          "type": "boolean",
                          "default": False
                      }
                  },
                  "required": ["mode"]
              }
          ),

• src/mcp_copyq/models.py:61-76 (schema)

  Pydantic model defining input parameters and validation for mcp_read.

  class ReadRequest(BaseModel):
      """Parameters for mcp_read tool."""
  
      mode: ReadMode = Field(..., description="Operation mode: tree, list, item, search")
      tab: str = Field(default="", description="Tab path: 'info', 'workspace/proj1' or full path like '&clipboard'")
      index: int | None = Field(default=None, description="Item index (for mode=item)")
      query: str | None = Field(default=None, description="Search query regex (for mode=search)")
      search_in: SearchIn = Field(default=SearchIn.ALL, description="Where to search")
      scope: Scope = Field(default=Scope.MCP, description="Tab scope: mcp (default), all, external")
      max_depth: int = Field(default=2, ge=1, le=10, description="Max depth for tree")
      max_items: int = Field(default=20, ge=1, le=100, description="Max items to return")
      skip: int = Field(default=0, ge=0, description="Skip N items (pagination)")
      include_text: bool = Field(default=True, description="Include text/preview")
      include_tags: bool = Field(default=True, description="Include tags")
      include_note: bool = Field(default=False, description="Include note")

• src/mcp_copyq/server.py:238-240 (registration)

  Dispatch from MCP server's call_tool handler to the mcp_read function.

  if name == "mcp_read":
      result = await mcp_read(**arguments)
  elif name == "mcp_write":

• src/mcp_copyq/tools/read.py:95-186 (helper)

  Helper function for 'tree' mode, building hierarchical tab structure with previews.

  async def _read_tree(
      max_depth: int,
      max_items: int,
      include_text: bool,
      include_tags: bool,
      scope: str = "mcp",
  ) -> str:
      """Build tree structure of tabs."""
      # Get tabs based on scope
      if scope == "mcp":
          tabs = await client.list_tabs()
      elif scope == "external":
          tabs = await client.list_external_tabs()
      else:  # "all"
          tabs = await client.list_all_tabs()
  
      lines = []
  
      async def format_tab(
          path: str,
          depth: int,
          indent: str = "",
          is_external: bool = False
      ) -> None:
          if depth > max_depth:
              return
  
          count = await client.get_count(path, external=is_external)
  
          # Clean path for display
          if path.startswith(f"{MCP_ROOT}/"):
              display_path = path[len(MCP_ROOT) + 1:]
          else:
              display_path = path
  
          # Mark external tabs
          external_marker = " [external]" if is_external else ""
          lines.append(f"{indent}{display_path} [{count}]{external_marker}")
  
          # Add preview items
          preview_count = min(count, max_items)
          for i in range(preview_count):
              preview = await client.read_item_preview(path, i, external=is_external)
  
              parts = [f"{indent}  {i}:"]
              if include_text:
                  parts.append(f'"{preview["text_preview"]}"')
              if include_tags and preview["tags"]:
                  parts.append(f"[{','.join(preview['tags'])}]")
              if preview["has_note"]:
                  parts.append("+note")
  
              lines.append("|".join(parts) if len(parts) > 1 else parts[0])
  
          # Find child tabs
          child_tabs = [t for t in tabs if t.startswith(path + "/") and t.count("/") == path.count("/") + 1]
          for child in child_tabs:
              child_is_external = not child.startswith(f"{MCP_ROOT}/")
              await format_tab(child, depth + 1, indent + "  ", child_is_external)
  
      if scope == "mcp":
          # Start from mcp root tabs
          for root in ALLOWED_ROOT_TABS:
              full_path = f"{MCP_ROOT}/{root}"
              if full_path in tabs or any(t.startswith(full_path + "/") for t in tabs):
                  await format_tab(full_path, 1, "", False)
      else:
          # For all/external scope, show root-level tabs
          root_tabs = [t for t in tabs if "/" not in t or (t.count("/") == 1 and t.startswith(f"{MCP_ROOT}/"))]
  
          # Also get direct children of mcp/ for "all" scope
          if scope == "all":
              # Get unique root tabs (either no "/" or first level of mcp/)
              seen_roots = set()
              for t in tabs:
                  if t.startswith(f"{MCP_ROOT}/"):
                      # For mcp tabs, get first level after mcp/
                      parts = t.split("/")
                      if len(parts) >= 2:
                          seen_roots.add(f"{MCP_ROOT}/{parts[1]}")
                  else:
                      # For external tabs, get root
                      root = t.split("/")[0]
                      seen_roots.add(root)
              root_tabs = sorted(seen_roots)
  
          for tab in root_tabs:
              is_external = not tab.startswith(f"{MCP_ROOT}/")
              await format_tab(tab, 1, "", is_external)
  
      return "\n".join(lines) if lines else "empty|no tabs found"