find

Instructions

Implementation Reference

• src/server/cli.py:47-69 (handler)

  The MCP tool 'find' handler function that searches notes via text and optional filters (labels, colors, pinned, archived, trashed), serializes results to JSON.

  @mcp.tool()
  def find(
      query: str = "",
      labels: list[str] | None = None,
      colors: list[str] | None = None,
      pinned: bool | None = None,
      archived: bool | None = False,
      trashed: bool = False,
  ) -> str:
      """Find notes using text and optional filters. labels should be label IDs. colors should be ColorValue strings (e.g. DEFAULT, RED, CERULEAN)."""
      keep = get_client()
      normalized_colors = _normalize_colors(colors)
      notes = keep.find(
          query=query,
          labels=labels,
          colors=normalized_colors,
          pinned=pinned,
          archived=archived,
          trashed=trashed,
      )
  
      notes_data = [serialize_note(note) for note in notes]
      return json.dumps(notes_data)

• src/server/cli.py:48-69 (schema)

  The input parameters/type hints and return type for the 'find' tool: query (str), labels (list[str]|None), colors (list[str]|None), pinned/bool|None, archived/bool|None (default False), trashed/bool (default False). Returns JSON string.

  def find(
      query: str = "",
      labels: list[str] | None = None,
      colors: list[str] | None = None,
      pinned: bool | None = None,
      archived: bool | None = False,
      trashed: bool = False,
  ) -> str:
      """Find notes using text and optional filters. labels should be label IDs. colors should be ColorValue strings (e.g. DEFAULT, RED, CERULEAN)."""
      keep = get_client()
      normalized_colors = _normalize_colors(colors)
      notes = keep.find(
          query=query,
          labels=labels,
          colors=normalized_colors,
          pinned=pinned,
          archived=archived,
          trashed=trashed,
      )
  
      notes_data = [serialize_note(note) for note in notes]
      return json.dumps(notes_data)

• src/server/cli.py:47-47 (registration)

  The tool is registered as an MCP tool via the @mcp.tool() decorator.

  @mcp.tool()

• src/server/cli.py:33-44 (helper)

  Helper function _normalize_colors converts string color names to gkeepapi ColorValue enum values, raising on invalid colors.

  def _normalize_colors(colors: list[str] | None):
      if colors is None:
          return None
  
      normalized_colors = []
      for color in colors:
          try:
              normalized_colors.append(gkeepapi.node.ColorValue(color))
          except ValueError as exc:
              raise ValueError(f"Invalid color '{color}'") from exc
  
      return normalized_colors

• src/server/keep_api.py:10-56 (helper)

  Helper function get_client() initializes/reuses the gkeepapi Keep client used by find().

  def get_client():
      """
      Get or initialize the Google Keep client.
      This ensures we only authenticate once and reuse the client.
      
      Returns:
          gkeepapi.Keep: Authenticated Keep client
      """
      global _keep_client
      
      if _keep_client is not None:
          return _keep_client
      
      # Load environment variables
      load_dotenv()
      
      # Get credentials from environment variables
      email = os.getenv('GOOGLE_EMAIL')
      master_token = os.getenv('GOOGLE_MASTER_TOKEN')
      
      if not email or not master_token:
          raise ValueError("Missing Google Keep credentials. Please set GOOGLE_EMAIL and GOOGLE_MASTER_TOKEN environment variables.")
      
      # Initialize the Keep API
      keep = gkeepapi.Keep()
      
      # Authenticate
      try:
          keep.authenticate(email, master_token)
      except requests.exceptions.JSONDecodeError as exc:
          raise RuntimeError(
              "Google Keep API returned a non-JSON response during authentication. "
              "This usually means the unofficial Keep API (notes/v1) is inaccessible "
              "from this environment (HTTP 403/4xx). "
              "Check that your GOOGLE_MASTER_TOKEN is valid and that the Keep API "
              "is reachable from this network."
          ) from exc
      except gkeepapi.exception.LoginException as exc:
          raise RuntimeError(
              f"Google Keep login failed: {exc}. "
              "Verify that GOOGLE_EMAIL and GOOGLE_MASTER_TOKEN are correct."
          ) from exc
      
      # Store the client for reuse
      _keep_client = keep
      
      return keep