search_clipboard

Instructions

Implementation Reference

• packages/screen/src/contextpulse_sight/mcp_server.py:708-738 (handler)

  MCP tool handler that searches clipboard history by text query. Decorated with @mcp_app.tool() and @_track_call. Clamps minutes_ago to [1,10080], validates query, delegates DB search to _activity_db.search_clipboard(), formats results as a formatted string with timestamps and previews.

  @mcp_app.tool()
  @_track_call
  def search_clipboard(query: str, minutes_ago: int = 60) -> str:
      """Search clipboard history for specific text.
  
      Searches through captured clipboard contents. Useful for finding a
      specific error message, URL, or code snippet that was copied earlier.
  
      Args:
          query: Text to search for in clipboard history.
          minutes_ago: How far back to search (default 60 minutes).
      """
      minutes_ago = max(1, min(minutes_ago, 10080))
      if not query or not query.strip():
          return "Search query cannot be empty."
      results = _activity_db.search_clipboard(query, minutes_ago)
      if not results:
          return f"No clipboard entries matching '{query}' in the last {minutes_ago} minutes."
  
      lines = [f"=== Clipboard Search: '{query}' ({len(results)} results) ===\n"]
      for entry in results:
          ts_str = datetime.fromtimestamp(entry["timestamp"]).strftime("%H:%M:%S")
          text = entry["text"]
          preview = text[:300].replace("\n", " \\n ")
          if len(text) > 300:
              preview += "..."
          lines.append(f"[{ts_str}] ({len(text)} chars)")
          lines.append(f"  {preview}")
          lines.append("")
  
      return "\n".join(lines)

• packages/screen/src/contextpulse_sight/activity.py:289-300 (helper)

  SQLite-backed helper method ActivityDB.search_clipboard() that performs a LIKE query on the clipboard table, filtering by text match and timestamp cutoff, returning up to 20 results as dicts.

  def search_clipboard(self, query: str, minutes_ago: int = 60) -> list[dict]:
      """Search clipboard history by text content."""
      cutoff = time.time() - (minutes_ago * 60)
      like_query = f"%{query}%"
      with self._lock:
          rows = self._conn.execute(
              "SELECT id, timestamp, text FROM clipboard "
              "WHERE text LIKE ? AND timestamp >= ? "
              "ORDER BY timestamp DESC LIMIT 20",
              (like_query, cutoff),
          ).fetchall()
      return [dict(row) for row in rows]

• packages/screen/src/contextpulse_sight/mcp_server.py:708-738 (registration)

  Tool registration via @mcp_app.tool() decorator on the search_clipboard function in the ContextPulse Sight MCP server.

  @mcp_app.tool()
  @_track_call
  def search_clipboard(query: str, minutes_ago: int = 60) -> str:
      """Search clipboard history for specific text.
  
      Searches through captured clipboard contents. Useful for finding a
      specific error message, URL, or code snippet that was copied earlier.
  
      Args:
          query: Text to search for in clipboard history.
          minutes_ago: How far back to search (default 60 minutes).
      """
      minutes_ago = max(1, min(minutes_ago, 10080))
      if not query or not query.strip():
          return "Search query cannot be empty."
      results = _activity_db.search_clipboard(query, minutes_ago)
      if not results:
          return f"No clipboard entries matching '{query}' in the last {minutes_ago} minutes."
  
      lines = [f"=== Clipboard Search: '{query}' ({len(results)} results) ===\n"]
      for entry in results:
          ts_str = datetime.fromtimestamp(entry["timestamp"]).strftime("%H:%M:%S")
          text = entry["text"]
          preview = text[:300].replace("\n", " \\n ")
          if len(text) > 300:
              preview += "..."
          lines.append(f"[{ts_str}] ({len(text)} chars)")
          lines.append(f"  {preview}")
          lines.append("")
  
      return "\n".join(lines)

• packages/screen/src/contextpulse_sight/mcp_server.py:710-719 (schema)

  Input schema: query (str, required), minutes_ago (int, default 60). Output is a formatted str.

  def search_clipboard(query: str, minutes_ago: int = 60) -> str:
      """Search clipboard history for specific text.
  
      Searches through captured clipboard contents. Useful for finding a
      specific error message, URL, or code snippet that was copied earlier.
  
      Args:
          query: Text to search for in clipboard history.
          minutes_ago: How far back to search (default 60 minutes).
      """

• glama/server.py:590-607 (handler)

  Glama.ai registry stub for search_clipboard — returns _LOCAL_ONLY_MSG because ContextPulse only runs locally; this is just for registry discovery.

  @mcp_app.tool()
  def search_clipboard(query: str, limit: int = 20) -> str:
      """Full-text search over the clipboard history.
  
      Returns matching entries with timestamp, snippet, and source application.
  
      USE WHEN: the user asks "find that thing I copied about X" / "did I copy
      the bug ID."
      NOT FOR: non-text clipboard content — only text entries are indexed.
  
      BEHAVIOR: pure read. Sensitive entries are excluded from the index (see
      get_clipboard_history).
  
      PARAMETERS:
        query: substring or FTS expression. Required, non-empty.
        limit: max results. Range 1-100. Default 20.
      """
      return _LOCAL_ONLY_MSG