keep-mcp 2.2.1__tar.gz → 2.3.0__tar.gz

{keep_mcp-2.2.1 → keep_mcp-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: keep-mcp
-Version: 2.2.1
+Version: 2.3.0
 Summary: MCP Server for Google Keep
 Project-URL: Homepage, https://github.com/feuerdev/keep-mcp
 Project-URL: Repository, https://github.com/feuerdev/keep-mcp

{keep_mcp-2.2.1 → keep_mcp-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "keep-mcp"
-version = "2.2.1"
+version = "2.3.0"
 description = "MCP Server for Google Keep"
 readme = "README.md"
 requires-python = ">=3.10"

{keep_mcp-2.2.1 → keep_mcp-2.3.0}/scripts/smoke_test.py

@@ -17,7 +17,6 @@ This script performs a lifecycle against Google Keep:
 It is intended for manual verification, not CI.
 """
 
-import json
 import os
 import sys
 from pathlib import Path
@@ -33,93 +32,93 @@ def main() -> None:
 
     # --- Note lifecycle ---
     print("Creating note...")
-    created = json.loads(cli.create_note(title="keep-mcp smoke", text="hello"))
+    created = cli.create_note(title="keep-mcp smoke", text="hello")
     note_id = created["id"]
     print("Created:", note_id)
 
     print("Updating note...")
-    updated = json.loads(cli.update_note(note_id, title="keep-mcp smoke updated", text="world"))
+    updated = cli.update_note(note_id, title="keep-mcp smoke updated", text="world")
     assert updated["title"] == "keep-mcp smoke updated"
 
     print("Setting color...")
-    colored = json.loads(cli.set_note_color(note_id, "RED"))
+    colored = cli.set_note_color(note_id, "RED")
     assert colored["color"] == "RED"
     # Reset to default
-    json.loads(cli.set_note_color(note_id, "DEFAULT"))
+    cli.set_note_color(note_id, "DEFAULT")
 
     print("Pin/unpin...")
-    assert json.loads(cli.pin_note(note_id, True))["pinned"] is True
-    assert json.loads(cli.pin_note(note_id, False))["pinned"] is False
+    assert cli.pin_note(note_id, True)["pinned"] is True
+    assert cli.pin_note(note_id, False)["pinned"] is False
 
     print("Archive/unarchive...")
-    assert json.loads(cli.archive_note(note_id, True))["archived"] is True
-    assert json.loads(cli.archive_note(note_id, False))["archived"] is False
+    assert cli.archive_note(note_id, True)["archived"] is True
+    assert cli.archive_note(note_id, False)["archived"] is False
 
     print("Trash/restore...")
-    assert json.loads(cli.trash_note(note_id))["trashed"] is True
-    restored = json.loads(cli.restore_note(note_id))
+    assert cli.trash_note(note_id)["trashed"] is True
+    restored = cli.restore_note(note_id)
     assert restored["trashed"] is False
 
     print("Deleting note...")
-    delete_msg = json.loads(cli.delete_note(note_id))
+    delete_msg = cli.delete_note(note_id)
     assert "marked for deletion" in delete_msg["message"]
 
     # --- Checklist lifecycle ---
     print("Creating list...")
-    lst = json.loads(cli.create_list("keep-mcp smoke list", items=[{"text": "item1", "checked": False}]))
+    lst = cli.create_list("keep-mcp smoke list", items=[{"text": "item1", "checked": False}])
     list_id = lst["id"]
     print("List created:", list_id)
     assert lst["items"][0]["text"] == "item1"
 
     print("Adding list item...")
-    added = json.loads(cli.add_list_item(list_id, "item2", checked=False))
+    added = cli.add_list_item(list_id, "item2", checked=False)
     item_id = added["item_id"]
 
     print("Updating list item...")
-    updated_list = json.loads(cli.update_list_item(list_id, item_id, text="item2 edited", checked=True))
+    updated_list = cli.update_list_item(list_id, item_id, text="item2 edited", checked=True)
     edited = next(i for i in updated_list["items"] if i["id"] == item_id)
     assert edited["text"] == "item2 edited"
     assert edited["checked"] is True
 
     print("Deleting list item...")
-    del_item = json.loads(cli.delete_list_item(list_id, item_id))
+    del_item = cli.delete_list_item(list_id, item_id)
     assert "marked for deletion" in del_item["message"]
 
     print("Deleting list note...")
-    json.loads(cli.delete_note(list_id))
+    cli.delete_note(list_id)
 
     # --- Label lifecycle ---
     print("Creating label...")
-    label = json.loads(cli.create_label("keep-mcp-smoke-label"))
+    label = cli.create_label("keep-mcp-smoke-label")
     label_id = label["id"]
     print("Label created:", label_id)
 
     print("Listing labels (should include new label)...")
-    labels = json.loads(cli.list_labels())
+    labels = cli.list_labels()
     assert any(lb["id"] == label_id for lb in labels)
 
     print("Creating note for label association...")
-    note_for_label = json.loads(cli.create_note(title="label test"))
+    note_for_label = cli.create_note(title="label test")
     nfl_id = note_for_label["id"]
 
     print("Adding label to note...")
-    labeled = json.loads(cli.add_label_to_note(nfl_id, label_id))
+    labeled = cli.add_label_to_note(nfl_id, label_id)
     assert any(lb["id"] == label_id for lb in labeled["labels"])
 
     print("Removing label from note...")
-    unlabeled = json.loads(cli.remove_label_from_note(nfl_id, label_id))
+    unlabeled = cli.remove_label_from_note(nfl_id, label_id)
     assert all(lb["id"] != label_id for lb in unlabeled["labels"])
 
     print("Deleting label...")
-    del_label = json.loads(cli.delete_label(label_id))
+    del_label = cli.delete_label(label_id)
     assert "marked for deletion" in del_label["message"]
 
     print("Cleaning up label test note...")
-    json.loads(cli.delete_note(nfl_id))
+    cli.delete_note(nfl_id)
 
     # --- find() ---
     print("Testing find()...")
-    results = json.loads(cli.find(query="keep-mcp"))
+    results = cli.find(query="keep-mcp")
     assert isinstance(results, list)
 
     print("Smoke test finished successfully")

{keep_mcp-2.2.1 → keep_mcp-2.3.0}/src/server/cli.py

@@ -4,7 +4,6 @@ Provides tools for interacting with Google Keep notes through MCP.
 """
 
 import argparse
-import json
 import os
 import re
 from datetime import datetime, timezone
@@ -13,6 +12,8 @@ from typing import Any
 
 import gkeepapi
 from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
 
 from .keep_api import (
     KEEP_MCP_LABEL,
@@ -29,18 +30,21 @@ from .keep_api import (
 
 mcp = MCPServer("keep")
 
+READ_ONLY = ToolAnnotations(readOnlyHint=True)
+ADDITIVE = ToolAnnotations(destructiveHint=False)
+
 
 def _get_note_or_raise(note_id: str):
     keep = get_client()
     note = keep.get(note_id)
     if not note:
-        raise ValueError(f"Note with ID {note_id} not found")
+        raise ToolError(f"Note with ID {note_id} not found")
     return keep, note
 
 
 def _ensure_modifiable(note):
     if not can_modify_note(note):
-        raise ValueError(
+        raise ToolError(
             f"Note with ID {note.id} cannot be modified "
             "(missing keep-mcp label and UNSAFE_MODE is not enabled)"
         )
@@ -55,7 +59,7 @@ def _normalize_colors(colors: list[str] | None):
         try:
             normalized_colors.append(gkeepapi.node.ColorValue(color))
         except ValueError as exc:
-            raise ValueError(f"Invalid color '{color}'") from exc
+            raise ToolError(f"Invalid color '{color}'") from exc
 
     return normalized_colors
 
@@ -66,7 +70,7 @@ def _parse_utc(value: str | None, param: str) -> datetime | None:
     try:
         parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
     except ValueError as exc:
-        raise ValueError(
+        raise ToolError(
             f"Invalid {param} '{value}': expected ISO 8601, "
             "e.g. 2026-07-29 or 2026-07-29T12:00:00Z"
         ) from exc
@@ -105,7 +109,7 @@ def _build_time_filter(
     return within
 
 
-@mcp.tool()
+@mcp.tool(annotations=READ_ONLY)
 @keep_operation
 def find(
     query: str = "",
@@ -120,7 +124,7 @@ def find(
     updated_after: str | None = None,
     updated_before: str | None = None,
     limit: int | None = None,
-) -> str:
+) -> list[dict[str, Any]]:
     """Find notes using text and optional filters.
 
     query matches title and text, case-insensitively unless case_sensitive
@@ -157,20 +161,20 @@ def find(
         notes = islice(notes, max(limit, 0))
 
     notes_data = [serialize_note(note) for note in notes]
-    return json.dumps(notes_data)
+    return notes_data
 
 
-@mcp.tool()
+@mcp.tool(annotations=READ_ONLY)
 @keep_operation
-def get_note(note_id: str) -> str:
+def get_note(note_id: str) -> dict[str, Any]:
     """Get a note by ID."""
     _, note = _get_note_or_raise(note_id)
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
-@mcp.tool()
+@mcp.tool(annotations=ADDITIVE)
 @keep_operation
-def create_note(title: str | None = None, text: str | None = None) -> str:
+def create_note(title: str | None = None, text: str | None = None) -> dict[str, Any]:
     """Create a new note with title and text."""
     keep = get_client()
     note = keep.createNote(title=title, text=text)
@@ -182,12 +186,12 @@ def create_note(title: str | None = None, text: str | None = None) -> str:
     note.labels.add(label)
     keep.sync()
 
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
-@mcp.tool()
+@mcp.tool(annotations=ADDITIVE)
 @keep_operation
-def create_list(title: str | None = None, items: list[dict[str, Any]] | None = None) -> str:
+def create_list(title: str | None = None, items: list[dict[str, Any]] | None = None) -> dict[str, Any]:
     """
     Create a new checklist note.
 
@@ -199,7 +203,7 @@ def create_list(title: str | None = None, items: list[dict[str, Any]] | None = N
     if items:
         for item in items:
             if not isinstance(item.get("checked", False), bool):
-                raise TypeError("Each item's checked field must be a boolean")
+                raise ToolError("Each item's checked field must be a boolean")
         formatted_items = [
             (item.get("text", ""), item.get("checked", False)) for item in items
         ]
@@ -212,37 +216,37 @@ def create_list(title: str | None = None, items: list[dict[str, Any]] | None = N
     note.labels.add(label)
 
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
-@mcp.tool()
+@mcp.tool(annotations=ADDITIVE)
 @keep_operation
-def add_list_item(note_id: str, text: str, checked: bool = False) -> str:
+def add_list_item(note_id: str, text: str, checked: bool = False) -> dict[str, Any]:
     """Add an item to a checklist note."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     if not isinstance(note, gkeepapi.node.List):
-        raise TypeError(f"Note with ID {note_id} is not a list")
+        raise ToolError(f"Note with ID {note_id} is not a list")
 
     item = note.add(text=text, checked=checked)
     keep.sync()
-    return json.dumps({"note_id": note.id, "item_id": item.id})
+    return {"note_id": note.id, "item_id": item.id}
 
 
 @mcp.tool()
 @keep_operation
-def update_list_item(note_id: str, item_id: str, text: str | None = None, checked: bool | None = None) -> str:
+def update_list_item(note_id: str, item_id: str, text: str | None = None, checked: bool | None = None) -> dict[str, Any]:
     """Update checklist item text and/or checked state."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     if not isinstance(note, gkeepapi.node.List):
-        raise TypeError(f"Note with ID {note_id} is not a list")
+        raise ToolError(f"Note with ID {note_id} is not a list")
 
     item = note.get(item_id)
     if not item:
-        raise ValueError(f"List item with ID {item_id} not found")
+        raise ToolError(f"List item with ID {item_id} not found")
 
     if text is not None:
         item.text = text
@@ -250,37 +254,37 @@ def update_list_item(note_id: str, item_id: str, text: str | None = None, checke
         item.checked = checked
 
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
 @mcp.tool()
 @keep_operation
-def delete_list_item(note_id: str, item_id: str) -> str:
+def delete_list_item(note_id: str, item_id: str) -> dict[str, Any]:
     """Delete a checklist item."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     if not isinstance(note, gkeepapi.node.List):
-        raise TypeError(f"Note with ID {note_id} is not a list")
+        raise ToolError(f"Note with ID {note_id} is not a list")
 
     item = note.get(item_id)
     if not item:
-        raise ValueError(f"List item with ID {item_id} not found")
+        raise ToolError(f"List item with ID {item_id} not found")
 
     item.delete()
     keep.sync()
-    return json.dumps({"message": f"List item {item_id} marked for deletion"})
+    return {"message": f"List item {item_id} marked for deletion"}
 
 
 @mcp.tool()
 @keep_operation
-def update_note(note_id: str, title: str | None = None, text: str | None = None) -> str:
+def update_note(note_id: str, title: str | None = None, text: str | None = None) -> dict[str, Any]:
     """Update a note's title and text, or a checklist's title. Use item tools for checklist text."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     if text is not None and isinstance(note, gkeepapi.node.List):
-        raise ValueError("Cannot replace checklist text: use the checklist item tools")
+        raise ToolError("Cannot replace checklist text: use the checklist item tools")
 
     if title is not None:
         note.title = title
@@ -288,12 +292,12 @@ def update_note(note_id: str, title: str | None = None, text: str | None = None)
         note.text = text
 
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
 @mcp.tool()
 @keep_operation
-def set_note_color(note_id: str, color: str) -> str:
+def set_note_color(note_id: str, color: str) -> dict[str, Any]:
     """Set a note color. Valid values: DEFAULT (white), RED, ORANGE, YELLOW, GREEN, TEAL, BLUE, CERULEAN (dark blue), PURPLE, PINK, BROWN, GRAY."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
@@ -301,51 +305,51 @@ def set_note_color(note_id: str, color: str) -> str:
     try:
         note.color = gkeepapi.node.ColorValue(color)
     except ValueError as exc:
-        raise ValueError(f"Invalid color '{color}'") from exc
+        raise ToolError(f"Invalid color '{color}'") from exc
 
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
 @mcp.tool()
 @keep_operation
-def pin_note(note_id: str, pinned: bool = True) -> str:
+def pin_note(note_id: str, pinned: bool = True) -> dict[str, Any]:
     """Pin or unpin a note."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     note.pinned = pinned
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
 @mcp.tool()
 @keep_operation
-def archive_note(note_id: str, archived: bool = True) -> str:
+def archive_note(note_id: str, archived: bool = True) -> dict[str, Any]:
     """Archive or unarchive a note."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     note.archived = archived
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
 @mcp.tool()
 @keep_operation
-def trash_note(note_id: str) -> str:
+def trash_note(note_id: str) -> dict[str, Any]:
     """Move a note to trash."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     note.trash()
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
 @mcp.tool()
 @keep_operation
-def restore_note(note_id: str) -> str:
+def restore_note(note_id: str) -> dict[str, Any]:
     """Restore a trashed/deleted note."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
@@ -353,50 +357,50 @@ def restore_note(note_id: str) -> str:
     note.untrash()
     note.undelete()
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
 @mcp.tool()
 @keep_operation
-def delete_note(note_id: str) -> str:
+def delete_note(note_id: str) -> dict[str, Any]:
     """Delete a note (mark for deletion)."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     note.delete()
     keep.sync()
-    return json.dumps({"message": f"Note {note_id} marked for deletion"})
+    return {"message": f"Note {note_id} marked for deletion"}
 
 
-@mcp.tool()
+@mcp.tool(annotations=READ_ONLY)
 @keep_operation
-def list_labels() -> str:
+def list_labels() -> list[dict[str, Any]]:
     """List all labels."""
     keep = get_client()
-    return json.dumps([serialize_label(label) for label in keep.labels()])
+    return [serialize_label(label) for label in keep.labels()]
 
 
-@mcp.tool()
+@mcp.tool(annotations=ADDITIVE)
 @keep_operation
-def create_label(name: str) -> str:
+def create_label(name: str) -> dict[str, Any]:
     """Create a label."""
     keep = get_client()
     label = keep.createLabel(name)
     keep.sync()
-    return json.dumps(serialize_label(label))
+    return serialize_label(label)
 
 
 @mcp.tool()
 @keep_operation
-def delete_label(label_id: str) -> str:
+def delete_label(label_id: str) -> dict[str, Any]:
     """Delete a label by ID."""
     keep = get_client()
     label = keep.getLabel(label_id)
     if not label:
-        raise ValueError(f"Label with ID {label_id} not found")
+        raise ToolError(f"Label with ID {label_id} not found")
     if not is_unsafe_mode():
         if label.name == KEEP_MCP_LABEL:
-            raise ValueError(
+            raise ToolError(
                 f"Cannot delete the '{KEEP_MCP_LABEL}' label in safe mode: all notes managed "
                 "by this server would become permanently unmodifiable. Set UNSAFE_MODE=true to override."
             )
@@ -405,88 +409,88 @@ def delete_label(label_id: str) -> str:
             if any(lb.id == label_id for lb in n.labels.all()) and not has_keep_mcp_label(n)
         ]
         if unmanaged:
-            raise ValueError(
+            raise ToolError(
                 f"Cannot delete label '{label.name}' in safe mode: it is attached to "
                 f"{len(unmanaged)} unmanaged note(s). Deleting it would silently modify "
                 "those notes. Set UNSAFE_MODE=true to override."
             )
     keep.deleteLabel(label_id)
     keep.sync()
-    return json.dumps({"message": f"Label {label_id} marked for deletion"})
+    return {"message": f"Label {label_id} marked for deletion"}
 
 
-@mcp.tool()
+@mcp.tool(annotations=ADDITIVE)
 @keep_operation
-def add_label_to_note(note_id: str, label_id: str) -> str:
+def add_label_to_note(note_id: str, label_id: str) -> dict[str, Any]:
     """Add a label to a note."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     label = keep.getLabel(label_id)
     if not label:
-        raise ValueError(f"Label with ID {label_id} not found")
+        raise ToolError(f"Label with ID {label_id} not found")
 
     note.labels.add(label)
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
 @mcp.tool()
 @keep_operation
-def remove_label_from_note(note_id: str, label_id: str) -> str:
+def remove_label_from_note(note_id: str, label_id: str) -> dict[str, Any]:
     """Remove a label from a note."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     label = keep.getLabel(label_id)
     if not label:
-        raise ValueError(f"Label with ID {label_id} not found")
+        raise ToolError(f"Label with ID {label_id} not found")
     if label.name == KEEP_MCP_LABEL and not is_unsafe_mode():
-        raise ValueError(
+        raise ToolError(
             f"Cannot remove the '{KEEP_MCP_LABEL}' label in safe mode: the note would "
             "become permanently unmodifiable. Set UNSAFE_MODE=true to override."
         )
 
     note.labels.remove(label)
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
-@mcp.tool()
+@mcp.tool(annotations=READ_ONLY)
 @keep_operation
-def list_note_collaborators(note_id: str) -> str:
+def list_note_collaborators(note_id: str) -> list[str]:
     """List collaborator emails for a note."""
     _, note = _get_note_or_raise(note_id)
-    return json.dumps(list(note.collaborators.all()))
+    return list(note.collaborators.all())
 
 
 @mcp.tool()
 @keep_operation
-def add_note_collaborator(note_id: str, email: str) -> str:
+def add_note_collaborator(note_id: str, email: str) -> dict[str, Any]:
     """Add a collaborator email to a note."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     note.collaborators.add(email)
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
 @mcp.tool()
 @keep_operation
-def remove_note_collaborator(note_id: str, email: str) -> str:
+def remove_note_collaborator(note_id: str, email: str) -> dict[str, Any]:
     """Remove a collaborator email from a note."""
     keep, note = _get_note_or_raise(note_id)
     _ensure_modifiable(note)
 
     note.collaborators.remove(email)
     keep.sync()
-    return json.dumps(serialize_note(note))
+    return serialize_note(note)
 
 
-@mcp.tool()
+@mcp.tool(annotations=READ_ONLY)
 @keep_operation
-def list_note_media(note_id: str) -> str:
+def list_note_media(note_id: str) -> list[dict[str, Any]]:
     """List note media blobs and direct media links when available."""
     keep, note = _get_note_or_raise(note_id)
 
@@ -500,12 +504,12 @@ def list_note_media(note_id: str) -> str:
             }
         )
 
-    return json.dumps(media)
+    return media
 
 
 @mcp.tool()
 @keep_operation
-def download_media(note_id: str, dest_dir: str, blob_id: str | None = None) -> str:
+def download_media(note_id: str, dest_dir: str, blob_id: str | None = None) -> list[dict[str, Any]]:
     """Download a note's media (images, drawings, audio) to a local directory.
 
     The links from list_note_media require Google authentication and answer
@@ -519,7 +523,7 @@ def download_media(note_id: str, dest_dir: str, blob_id: str | None = None) -> s
 
     blobs = [blob for blob in note.blobs if blob_id is None or blob.id == blob_id]
     if blob_id is not None and not blobs:
-        raise ValueError(f"Blob with ID {blob_id} not found on note {note_id}")
+        raise ToolError(f"Blob with ID {blob_id} not found on note {note_id}")
 
     os.makedirs(dest_dir, exist_ok=True)
 
@@ -539,7 +543,7 @@ def download_media(note_id: str, dest_dir: str, blob_id: str | None = None) -> s
             }
         )
 
-    return json.dumps(saved)
+    return saved
 
 
 def main():

{keep_mcp-2.2.1 → keep_mcp-2.3.0}/src/server/keep_api.py

@@ -5,6 +5,7 @@ from threading import RLock
 import gkeepapi
 import requests
 from dotenv import load_dotenv
+from mcp.server.mcpserver.exceptions import ToolError
 
 KEEP_MCP_LABEL = "keep-mcp"
 
@@ -20,6 +21,8 @@ def keep_operation(func):
         with _client_lock:
             try:
                 return func(*args, **kwargs)
+            except ToolError:
+                raise
             except Exception:
                 # A failed operation can leave unsaved or prematurely cleaned
                 # mutations in memory. Reload remote state on the next call.
@@ -51,7 +54,7 @@ def get_client():
     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.")
+        raise ToolError("Missing Google Keep credentials. Please set GOOGLE_EMAIL and GOOGLE_MASTER_TOKEN environment variables.")
     
     # Initialize the Keep API
     keep = gkeepapi.Keep()
@@ -60,7 +63,7 @@ def get_client():
     try:
         keep.authenticate(email, master_token)
     except requests.exceptions.JSONDecodeError as exc:
-        raise RuntimeError(
+        raise ToolError(
             "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). "
@@ -68,7 +71,7 @@ def get_client():
             "is reachable from this network."
         ) from exc
     except gkeepapi.exception.LoginException as exc:
-        raise RuntimeError(
+        raise ToolError(
             f"Google Keep login failed: {exc}. "
             "Verify that GOOGLE_EMAIL and GOOGLE_MASTER_TOKEN are correct."
         ) from exc

{keep_mcp-2.2.1 → keep_mcp-2.3.0}/tests/test_checklist_validation.py

@@ -1,10 +1,10 @@
 """Exercise checklist validation with real gkeepapi objects, without network calls."""
 
-import json
 from unittest.mock import Mock
 
 import gkeepapi
 import pytest
+from mcp.server.mcpserver.exceptions import ToolError
 
 from server import cli
 
@@ -20,18 +20,18 @@ def offline_keep(monkeypatch):
 
 @pytest.mark.parametrize("checked", ["false", "true", 0, 1, None])
 def test_create_list_rejects_non_boolean_checked_without_creating_note(offline_keep, checked):
-    with pytest.raises(TypeError, match="checked.*boolean"):
+    with pytest.raises(ToolError, match="checked.*boolean"):
         cli.create_list("Tasks", [{"text": "Buy milk", "checked": checked}])
     assert list(offline_keep.all()) == []
     offline_keep.sync.assert_not_called()
 
 
 def test_create_list_preserves_boolean_checked_and_default(offline_keep):
-    result = json.loads(cli.create_list("Tasks", [
+    result = cli.create_list("Tasks", [
         {"text": "Unchecked", "checked": False},
         {"text": "Checked", "checked": True},
         {"text": "Default"},
-    ]))
+    ])
     assert {item["text"]: item["checked"] for item in result["items"]} == {
         "Unchecked": False, "Checked": True, "Default": False,
     }
@@ -40,7 +40,7 @@ def test_create_list_preserves_boolean_checked_and_default(offline_keep):
 def test_update_list_text_does_not_partially_change_title(offline_keep):
     note = offline_keep.createList("Original", [("Buy milk", False)])
     note.labels.add(offline_keep.createLabel("keep-mcp"))
-    with pytest.raises(ValueError, match="checklist.*item"):
+    with pytest.raises(ToolError, match="checklist.*item"):
         cli.update_note(note.id, title="Changed", text="Replacement")
     assert note.title == "Original"
     assert [item.text for item in note.items] == ["Buy milk"]
@@ -50,6 +50,6 @@ def test_update_list_text_does_not_partially_change_title(offline_keep):
 def test_update_list_title_remains_supported(offline_keep):
     note = offline_keep.createList("Original", [("Buy milk", False)])
     note.labels.add(offline_keep.createLabel("keep-mcp"))
-    result = json.loads(cli.update_note(note.id, title="Changed"))
+    result = cli.update_note(note.id, title="Changed")
     assert result["title"] == "Changed"
     assert result["items"][0]["text"] == "Buy milk"

{keep_mcp-2.2.1 → keep_mcp-2.3.0}/tests/test_cli.py

@@ -1,9 +1,10 @@
-import json
 import re
 from datetime import datetime, timezone
 from types import SimpleNamespace
 
+import anyio
 import pytest
+from mcp.server.mcpserver.exceptions import ToolError
 
 from server import cli
 
@@ -194,8 +195,7 @@ def keep(monkeypatch):
 
 
 def test_find_forwards_filters(keep):
-    result = json.loads(
-        cli.find(
+    result = cli.find(
             query="q",
             labels=["l1"],
             colors=["red"],
@@ -203,7 +203,6 @@ def test_find_forwards_filters(keep):
             archived=False,
             trashed=False,
         )
-    )
     assert keep.last_find_kwargs["query"].pattern == "q"
     assert keep.last_find_kwargs["labels"] == ["l1"]
     assert [color.value for color in keep.last_find_kwargs["colors"]] == ["red"]
@@ -253,14 +252,14 @@ def test_find_date_filter_func(keep):
 
 
 def test_find_invalid_date_raises(keep):
-    with pytest.raises(ValueError, match="created_after"):
+    with pytest.raises(ToolError, match="created_after"):
         cli.find(created_after="not-a-date")
 
 
 def test_find_limit_caps_results(keep):
-    assert len(json.loads(cli.find())) == 2
-    assert len(json.loads(cli.find(limit=1))) == 1
-    assert json.loads(cli.find(limit=0)) == []
+    assert len(cli.find()) == 2
+    assert len(cli.find(limit=1)) == 1
+    assert cli.find(limit=0) == []
 
 
 def test_find_invalid_color_raises(keep, monkeypatch):
@@ -268,82 +267,88 @@ def test_find_invalid_color_raises(keep, monkeypatch):
         raise ValueError("bad")
 
     monkeypatch.setattr(cli.gkeepapi.node, "ColorValue", bad_color)
-    with pytest.raises(ValueError, match="Invalid color 'invalid'"):
+    with pytest.raises(ToolError, match="Invalid color 'invalid'"):
         cli.find(colors=["invalid"])
 
 
 def test_get_note(keep):
-    data = json.loads(cli.get_note("n1"))
+    data = cli.get_note("n1")
     assert data["id"] == "n1"
 
 
 def test_create_note_labels_and_sync(keep):
-    data = json.loads(cli.create_note("t", "body"))
+    data = cli.create_note("t", "body")
     assert data["id"] == "created"
     assert keep.sync_calls == 1
 
 
 def test_create_note_creates_label_when_missing(keep):
     keep._labels = {}
-    data = json.loads(cli.create_note("t", "body"))
+    data = cli.create_note("t", "body")
     assert data["labels"][0]["name"] == "keep-mcp"
 
 
 def test_create_list_variants(keep):
-    data = json.loads(cli.create_list("list"))
+    data = cli.create_list("list")
     assert data["id"] == "created_list"
-    data_with_items = json.loads(
-        cli.create_list("list", items=[{"text": "a", "checked": True}])
-    )
+    data_with_items = cli.create_list("list", items=[{"text": "a", "checked": True}])
     assert data_with_items["items"][0]["checked"] is True
 
 
 def test_create_list_creates_label_when_missing(keep):
     keep._labels = {}
-    data = json.loads(cli.create_list("list"))
+    data = cli.create_list("list")
     assert data["labels"][0]["name"] == "keep-mcp"
 
 
 def test_update_note_updates_fields(keep):
-    data = json.loads(cli.update_note("n1", title="new", text="changed"))
+    data = cli.update_note("n1", title="new", text="changed")
     assert data["title"] == "new"
     assert data["text"] == "changed"
 
 
+def test_anticipated_errors_reach_the_client(keep):
+    with pytest.raises(ToolError, match="Note with ID missing not found"):
+        anyio.run(cli.mcp.call_tool, "get_note", {"note_id": "missing"})
+
+
+def test_tools_return_structured_content(keep):
+    result = anyio.run(cli.mcp.call_tool, "get_note", {"note_id": "n1"})
+    assert result.structured_content["id"] == "n1"
+
+
 def test_update_note_not_found_raises(keep):
-    with pytest.raises(ValueError, match="not found"):
+    with pytest.raises(ToolError, match="not found"):
         cli.update_note("missing", title="x")
 
 
 def test_list_item_roundtrip(keep):
-    add = json.loads(cli.add_list_item("list1", "task", checked=True))
+    add = cli.add_list_item("list1", "task", checked=True)
     item_id = add["item_id"]
-    updated = json.loads(
-        cli.update_list_item("list1", item_id, text="task2", checked=False)
-    )
+    updated = cli.update_list_item("list1", item_id, text="task2", checked=False)
     assert any(item["id"] == item_id for item in updated["items"])
 
 
 def test_update_list_item_missing_item_raises(keep):
-    with pytest.raises(ValueError, match="not found"):
+    with pytest.raises(ToolError, match="not found"):
         cli.update_list_item("list1", "missing", text="x")
 
 
 def test_delete_list_item_paths(keep):
-    with pytest.raises(ValueError, match="not found"):
+    with pytest.raises(ToolError, match="not found"):
         cli.delete_list_item("list1", "missing")
 
-    new_item_id = json.loads(cli.add_list_item("list1", "task"))["item_id"]
-    data = json.loads(cli.delete_list_item("list1", new_item_id))
+    new_item_id = cli.add_list_item("list1", "task")["item_id"]
+    data = cli.delete_list_item("list1", new_item_id)
     assert "marked for deletion" in data["message"]
 
 
 def test_list_item_requires_list_type(keep):
-    with pytest.raises(TypeError, match="not a list"):
+    with pytest.raises(ToolError, match="not a list"):
         cli.add_list_item("n1", "x")
-    with pytest.raises(TypeError, match="not a list"):
+    with pytest.raises(ToolError, match="not a list"):
         cli.update_list_item("n1", "i1", text="x")
-    with pytest.raises(TypeError, match="not a list"):
+    with pytest.raises(ToolError, match="not a list"):
         cli.delete_list_item("n1", "i1")
 
 
@@ -352,43 +357,43 @@ def test_set_note_color_validates(keep, monkeypatch):
         raise ValueError("bad")
 
     monkeypatch.setattr(cli.gkeepapi.node, "ColorValue", bad_color)
-    with pytest.raises(ValueError, match="Invalid color"):
+    with pytest.raises(ToolError, match="Invalid color"):
         cli.set_note_color("n1", "invalid")
 
 
 def test_note_state_transitions(keep):
-    assert json.loads(cli.set_note_color("n1", "red"))["color"] == "red"
-    assert json.loads(cli.pin_note("n1", True))["pinned"] is True
-    assert json.loads(cli.archive_note("n1", True))["archived"] is True
-    assert json.loads(cli.trash_note("n1"))["trashed"] is True
-    assert json.loads(cli.restore_note("n1"))["trashed"] is False
+    assert cli.set_note_color("n1", "red")["color"] == "red"
+    assert cli.pin_note("n1", True)["pinned"] is True
+    assert cli.archive_note("n1", True)["archived"] is True
+    assert cli.trash_note("n1")["trashed"] is True
+    assert cli.restore_note("n1")["trashed"] is False
 
 
 def test_delete_note_marks_deleted(keep):
-    msg = json.loads(cli.delete_note("n1"))
+    msg = cli.delete_note("n1")
     assert "marked for deletion" in msg["message"]
 
 
 def test_label_crud_and_missing_label_errors(keep):
-    labels = json.loads(cli.list_labels())
+    labels = cli.list_labels()
     assert labels
 
-    created = json.loads(cli.create_label("other"))
+    created = cli.create_label("other")
     assert created["name"] == "other"
-    message = json.loads(cli.delete_label(created["id"]))
+    message = cli.delete_label(created["id"])
     assert "marked for deletion" in message["message"]
 
-    with pytest.raises(ValueError, match="Label with ID bad not found"):
+    with pytest.raises(ToolError, match="Label with ID bad not found"):
         cli.delete_label("bad")
-    with pytest.raises(ValueError, match="Label with ID bad not found"):
+    with pytest.raises(ToolError, match="Label with ID bad not found"):
         cli.add_label_to_note("n1", "bad")
-    with pytest.raises(ValueError, match="Label with ID bad not found"):
+    with pytest.raises(ToolError, match="Label with ID bad not found"):
         cli.remove_label_from_note("n1", "bad")
 
 
 def test_delete_label_safe_mode_guards(keep, monkeypatch):
     # Deleting the keep-mcp label is blocked in safe mode.
-    with pytest.raises(ValueError, match="keep-mcp"):
+    with pytest.raises(ToolError, match="keep-mcp"):
         cli.delete_label("l1")
 
     # Deleting a label that is on an unmanaged note is also blocked in safe mode.
@@ -397,41 +402,41 @@ def test_delete_label_safe_mode_guards(keep, monkeypatch):
     keep._labels["shared"] = shared
     unmanaged.labels.add(shared)
     keep.notes["unmanaged"] = unmanaged
-    with pytest.raises(ValueError, match="unmanaged"):
+    with pytest.raises(ToolError, match="unmanaged"):
         cli.delete_label("shared")
 
     # UNSAFE_MODE bypasses both guards.
     monkeypatch.setenv("UNSAFE_MODE", "true")
-    msg = json.loads(cli.delete_label("shared"))
+    msg = cli.delete_label("shared")
     assert "marked for deletion" in msg["message"]
 
 
 def test_label_add_remove(keep):
     keep._labels["l2"] = DummyLabel("l2", "other")
-    add = json.loads(cli.add_label_to_note("n1", "l2"))
+    add = cli.add_label_to_note("n1", "l2")
     assert any(label["id"] == "l2" for label in add["labels"])
-    remove = json.loads(cli.remove_label_from_note("n1", "l2"))
+    remove = cli.remove_label_from_note("n1", "l2")
     assert all(label["id"] != "l2" for label in remove["labels"])
 
 
 def test_collaborator_list_add_remove(keep):
-    before = json.loads(cli.list_note_collaborators("n1"))
+    before = cli.list_note_collaborators("n1")
     assert before == []
 
-    data = json.loads(cli.add_note_collaborator("n1", "user@example.com"))
+    data = cli.add_note_collaborator("n1", "user@example.com")
     assert "user@example.com" in data["collaborators"]
-    after = json.loads(cli.remove_note_collaborator("n1", "user@example.com"))
+    after = cli.remove_note_collaborator("n1", "user@example.com")
     assert "user@example.com" not in after["collaborators"]
 
 
 def test_list_note_media(keep):
-    media = json.loads(cli.list_note_media("n1"))
+    media = cli.list_note_media("n1")
     assert media[0]["media_link"].startswith("https://media/")
 
 
 def test_download_media_writes_files(keep, monkeypatch, tmp_path):
     monkeypatch.setattr(cli, "fetch_blob_bytes", lambda k, b: (b"png-bytes", "image/png"))
-    saved = json.loads(cli.download_media("n1", str(tmp_path)))
+    saved = cli.download_media("n1", str(tmp_path))
     assert saved[0]["blob_id"] == "b1"
     assert saved[0]["type"] == "IMAGE"
     assert saved[0]["path"].endswith("b1.png")
@@ -441,14 +446,14 @@ def test_download_media_writes_files(keep, monkeypatch, tmp_path):
 
 
 def test_download_media_unknown_blob(keep, tmp_path):
-    with pytest.raises(ValueError, match="Blob with ID nope not found"):
+    with pytest.raises(ToolError, match="Blob with ID nope not found"):
         cli.download_media("n1", str(tmp_path), blob_id="nope")
 
 
 def test_modification_guard_blocks_when_unlabeled(keep, monkeypatch):
     keep.notes["n1"].labels = DummyLabels()
     monkeypatch.setattr(cli, "can_modify_note", lambda _: False)
-    with pytest.raises(ValueError, match="cannot be modified"):
+    with pytest.raises(ToolError, match="cannot be modified"):
         cli.update_note("n1", title="x")
 
 

{keep_mcp-2.2.1 → keep_mcp-2.3.0}/tests/test_keep_client.py

@@ -1,4 +1,5 @@
 import pytest
+from mcp.server.mcpserver.exceptions import ToolError
 
 from server import keep_api
 
@@ -38,12 +39,21 @@ def test_get_client_raises_when_missing_credentials(monkeypatch):
     monkeypatch.setattr(keep_api, "load_dotenv", lambda: None)
     monkeypatch.setattr(keep_api.os, "getenv", lambda _key: None)
 
-    try:
+    with pytest.raises(ToolError, match="Missing Google Keep credentials"):
         keep_api.get_client()
-    except ValueError as exc:
-        assert "Missing Google Keep credentials" in str(exc)
-    else:
-        raise AssertionError("Expected ValueError for missing credentials")
+
+
+def test_tool_error_keeps_the_client(monkeypatch):
+    client = object()
+    monkeypatch.setattr(keep_api, "_keep_client", client)
+
+    @keep_api.keep_operation
+    def reject():
+        raise ToolError("rejected")
+
+    with pytest.raises(ToolError):
+        reject()
+    assert keep_api._keep_client is client
 
 
 def test_cached_client_refreshes_external_changes(monkeypatch):
@@ -144,7 +154,6 @@ def test_tools_do_not_overlap_access_to_shared_state(monkeypatch):
 
 @pytest.mark.parametrize("remote_committed", [False, True])
 def test_failed_write_does_not_leave_phantom_state_for_next_read(monkeypatch, remote_committed):
-    import json
 
     import gkeepapi
     import requests
@@ -186,5 +195,5 @@ def test_failed_write_does_not_leave_phantom_state_for_next_read(monkeypatch, re
         cli.update_note(note.id, title='Uncommitted title')
 
     assert any(node.get('title') == 'Uncommitted title' for node in requests_sent[1])
-    result = json.loads(cli.get_note(note.id))
+    result = cli.get_note(note.id)
     assert result['title'] == ('Uncommitted title' if remote_committed else 'Original title')