list_labels

Instructions

Implementation Reference

• src/server/cli.py:260-264 (handler)

  The tool handler for 'list_labels'. Decorated with @mcp.tool(), it calls get_client() and returns serialized labels as JSON.

  @mcp.tool()
  def list_labels() -> str:
      """List all labels."""
      keep = get_client()
      return json.dumps([serialize_label(label) for label in keep.labels()])

• src/server/keep_api.py:58-59 (helper)

  The serialize_label helper function that converts a label object into a dict with 'id' and 'name' fields.

  def serialize_label(label):
      return {'id': label.id, 'name': label.name}

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

  The get_client() helper that initializes/reuses the Google Keep client used by list_labels.

  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

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

  The tool is registered via the @mcp.tool() decorator on FastMCP instance 'mcp' (line 14).

  @mcp.tool()
  def list_labels() -> str:
      """List all labels."""
      keep = get_client()
      return json.dumps([serialize_label(label) for label in keep.labels()])

• src/server/cli.py:260-264 (schema)

  No input parameters; returns a str (JSON array of label objects with id/name). Implicitly defined by the function signature and return type.

  @mcp.tool()
  def list_labels() -> str:
      """List all labels."""
      keep = get_client()
      return json.dumps([serialize_label(label) for label in keep.labels()])