Add MCP ToolAnnotations to all 35 tools (readOnlyHint, destructiveHint, idempotentHint)

Author: bigcat88

src/nextcloud_mcp/annotations.py

@@ -0,0 +1,9 @@
+"""Shared MCP ToolAnnotations constants for Nextcloud tools."""
+
+from mcp.types import ToolAnnotations
+
+READONLY = ToolAnnotations(readOnlyHint=True)
+ADDITIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=False, idempotentHint=False)
+ADDITIVE_IDEMPOTENT = ToolAnnotations(readOnlyHint=False, destructiveHint=False, idempotentHint=True)
+DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True, idempotentHint=True)
+DESTRUCTIVE_NON_IDEMPOTENT = ToolAnnotations(readOnlyHint=False, destructiveHint=True, idempotentHint=False)

src/nextcloud_mcp/tools/activity.py

@@ -5,6 +5,7 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from ..annotations import READONLY
 from ..permissions import PermissionLevel, require_permission
 from ..state import get_client
 
@@ -52,7 +53,7 @@ def _format_activity(a: dict[str, Any]) -> dict[str, Any]:
 def register(mcp: FastMCP) -> None:
     """Register activity tools with the MCP server."""
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def get_activity(
         activity_filter: str = "all",

src/nextcloud_mcp/tools/comments.py

@@ -7,6 +7,7 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from ..annotations import ADDITIVE, ADDITIVE_IDEMPOTENT, DESTRUCTIVE, READONLY
 from ..permissions import PermissionLevel, require_permission
 from ..state import get_client
 
@@ -96,7 +97,7 @@ def _parse_comments_xml(xml_text: str) -> list[dict[str, Any]]:
 
 
 def _register_read_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def list_comments(file_id: int, limit: int = 20, offset: int = 0) -> str:
         """List comments on a file.
@@ -137,7 +138,7 @@ async def list_comments(file_id: int, limit: int = 20, offset: int = 0) -> str:
 
 
 def _register_write_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE)
     @require_permission(PermissionLevel.WRITE)
     async def add_comment(file_id: int, message: str) -> str:
         """Add a comment to a file.
@@ -169,7 +170,7 @@ async def add_comment(file_id: int, message: str) -> str:
         comment_id = location.rstrip("/").split("/")[-1] if location else "unknown"
         return json.dumps({"id": comment_id, "message": message}, indent=2)
 
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE_IDEMPOTENT)
     @require_permission(PermissionLevel.WRITE)
     async def edit_comment(file_id: int, comment_id: int, message: str) -> str:
         """Edit a comment on a file.
@@ -207,7 +208,7 @@ async def edit_comment(file_id: int, comment_id: int, message: str) -> str:
 
 
 def _register_destructive_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=DESTRUCTIVE)
     @require_permission(PermissionLevel.DESTRUCTIVE)
     async def delete_comment(file_id: int, comment_id: int) -> str:
         """Delete a comment from a file.

src/nextcloud_mcp/tools/files.py

@@ -5,6 +5,12 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from ..annotations import (
+    ADDITIVE_IDEMPOTENT,
+    DESTRUCTIVE,
+    DESTRUCTIVE_NON_IDEMPOTENT,
+    READONLY,
+)
 from ..client import NextcloudClient
 from ..permissions import PermissionLevel, require_permission
 from ..state import get_client, get_config
@@ -48,7 +54,7 @@ def _build_search_xml(user: str, query: str, path: str, limit: int, offset: int,
 
 
 def _register_read_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def list_directory(path: str = "/") -> str:
         """List files and folders in a Nextcloud directory.
@@ -67,7 +73,7 @@ async def list_directory(path: str = "/") -> str:
             entries = entries[1:]
         return json.dumps(entries, indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def get_file(path: str) -> str:
         """Read a file's content from Nextcloud.
@@ -88,7 +94,7 @@ async def get_file(path: str) -> str:
         except UnicodeDecodeError:
             return f"[Binary file, {len(content)} bytes. Use download tools for binary content.]"
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def search_files(
         query: str = "",
@@ -145,7 +151,7 @@ async def search_files(
 
 
 def _register_write_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE_IDEMPOTENT)
     @require_permission(PermissionLevel.WRITE)
     async def upload_file(path: str, content: str) -> str:
         """Upload or overwrite a text file in Nextcloud.
@@ -163,7 +169,7 @@ async def upload_file(path: str, content: str) -> str:
         await client.dav_put(path, content.encode("utf-8"), content_type="text/plain; charset=utf-8")
         return f"File uploaded successfully: {path}"
 
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE_IDEMPOTENT)
     @require_permission(PermissionLevel.WRITE)
     async def create_directory(path: str) -> str:
         """Create a new directory in Nextcloud.
@@ -180,7 +186,7 @@ async def create_directory(path: str) -> str:
 
 
 def _register_destructive_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=DESTRUCTIVE)
     @require_permission(PermissionLevel.DESTRUCTIVE)
     async def delete_file(path: str) -> str:
         """Delete a file or directory from Nextcloud.
@@ -197,7 +203,7 @@ async def delete_file(path: str) -> str:
         await client.dav_delete(path)
         return f"Deleted: {path}"
 
-    @mcp.tool()
+    @mcp.tool(annotations=DESTRUCTIVE_NON_IDEMPOTENT)
     @require_permission(PermissionLevel.DESTRUCTIVE)
     async def move_file(source: str, destination: str) -> str:
         """Move or rename a file/directory in Nextcloud.

src/nextcloud_mcp/tools/notifications.py

@@ -4,14 +4,15 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from ..annotations import DESTRUCTIVE, READONLY
 from ..permissions import PermissionLevel, require_permission
 from ..state import get_client
 
 
 def register(mcp: FastMCP) -> None:
     """Register notification tools with the MCP server."""
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def list_notifications() -> str:
         """List all notifications for the current Nextcloud user.
@@ -29,7 +30,7 @@ async def list_notifications() -> str:
         )
         return json.dumps(data, indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=DESTRUCTIVE)
     @require_permission(PermissionLevel.DESTRUCTIVE)
     async def dismiss_notification(notification_id: int) -> str:
         """Dismiss (permanently delete) a single notification by its ID.
@@ -48,7 +49,7 @@ async def dismiss_notification(notification_id: int) -> str:
         )
         return f"Notification {notification_id} dismissed."
 
-    @mcp.tool()
+    @mcp.tool(annotations=DESTRUCTIVE)
     @require_permission(PermissionLevel.DESTRUCTIVE)
     async def dismiss_all_notifications() -> str:
         """Dismiss (permanently delete) ALL notifications for the current user.

src/nextcloud_mcp/tools/talk.py

@@ -5,6 +5,7 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from ..annotations import ADDITIVE, ADDITIVE_IDEMPOTENT, DESTRUCTIVE, READONLY
 from ..permissions import PermissionLevel, require_permission
 from ..state import get_client
 
@@ -125,7 +126,7 @@ def _format_participant(p: dict[str, Any]) -> dict[str, Any]:
 def _register_read_tools(mcp: FastMCP) -> None:
     """Register read-only Talk tools."""
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def list_conversations(include_notifications_disabled: bool = False) -> str:
         """List all Talk conversations the current user is part of.
@@ -149,7 +150,7 @@ async def list_conversations(include_notifications_disabled: bool = False) -> st
         conversations = [_format_conversation(room) for room in data]
         return json.dumps(conversations, indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def get_conversation(token: str) -> str:
         """Get details about a specific Talk conversation.
@@ -165,7 +166,7 @@ async def get_conversation(token: str) -> str:
         data = await client.ocs_get(f"apps/spreed/api/v4/room/{token}")
         return json.dumps(_format_conversation(data), indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def get_messages(
         token: str,
@@ -218,7 +219,7 @@ async def get_messages(
 
         return "\n".join(lines)
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def get_participants(token: str) -> str:
         """List participants in a Talk conversation.
@@ -236,7 +237,7 @@ async def get_participants(token: str) -> str:
         participants = [_format_participant(p) for p in data]
         return json.dumps(participants, indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def get_poll(token: str, poll_id: int) -> str:
         """Get a poll from a Talk conversation.
@@ -264,7 +265,7 @@ async def get_poll(token: str, poll_id: int) -> str:
 def _register_poll_tools(mcp: FastMCP) -> None:
     """Register poll-related Talk tools (write + destructive)."""
 
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE)
     @require_permission(PermissionLevel.WRITE)
     async def create_poll(
         token: str,
@@ -304,7 +305,7 @@ async def create_poll(
         data = await client.ocs_post(f"apps/spreed/api/v1/poll/{token}", data=post_data)
         return json.dumps(_format_poll(data), indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE_IDEMPOTENT)
     @require_permission(PermissionLevel.WRITE)
     async def vote_poll(token: str, poll_id: int, option_ids: list[int]) -> str:
         """Vote on a poll in a Talk conversation.
@@ -332,7 +333,7 @@ async def vote_poll(token: str, poll_id: int, option_ids: list[int]) -> str:
         data = await client.ocs_post(f"apps/spreed/api/v1/poll/{token}/{poll_id}", data=post_data)
         return json.dumps(_format_poll(data), indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=DESTRUCTIVE)
     @require_permission(PermissionLevel.DESTRUCTIVE)
     async def close_poll(token: str, poll_id: int) -> str:
         """Close a poll in a Talk conversation.
@@ -358,7 +359,7 @@ async def close_poll(token: str, poll_id: int) -> str:
 def _register_write_tools(mcp: FastMCP) -> None:
     """Register write and destructive Talk tools for conversations and messages."""
 
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE)
     @require_permission(PermissionLevel.WRITE)
     async def send_message(token: str, message: str, reply_to: int = 0) -> str:
         """Send a chat message to a Talk conversation.
@@ -381,7 +382,7 @@ async def send_message(token: str, message: str, reply_to: int = 0) -> str:
         data = await client.ocs_post(f"apps/spreed/api/v1/chat/{token}", data=post_data)
         return json.dumps(_format_message_full(data), indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE)
     @require_permission(PermissionLevel.WRITE)
     async def create_conversation(
         room_type: int,
@@ -410,7 +411,7 @@ async def create_conversation(
         data = await client.ocs_post("apps/spreed/api/v4/room", data=post_data)
         return json.dumps(_format_conversation(data), indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=DESTRUCTIVE)
     @require_permission(PermissionLevel.DESTRUCTIVE)
     async def delete_message(token: str, message_id: int) -> str:
         """Delete a chat message from a Talk conversation.
@@ -429,7 +430,7 @@ async def delete_message(token: str, message_id: int) -> str:
         await client.ocs_delete(f"apps/spreed/api/v1/chat/{token}/{message_id}")
         return f"Message {message_id} deleted from conversation {token}."
 
-    @mcp.tool()
+    @mcp.tool(annotations=DESTRUCTIVE)
     @require_permission(PermissionLevel.DESTRUCTIVE)
     async def leave_conversation(token: str) -> str:
         """Leave a Talk conversation.

src/nextcloud_mcp/tools/user_status.py

@@ -5,6 +5,7 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from ..annotations import ADDITIVE_IDEMPOTENT, READONLY
 from ..client import NextcloudError
 from ..permissions import PermissionLevel, require_permission
 from ..state import get_client, get_config
@@ -23,7 +24,7 @@ def _format_status(data: dict[str, Any]) -> dict[str, Any]:
 
 
 def _register_read_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def get_user_status(user_id: str = "") -> str:
         """Get the status of a Nextcloud user.
@@ -53,7 +54,7 @@ async def get_user_status(user_id: str = "") -> str:
 
 
 def _register_write_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE_IDEMPOTENT)
     @require_permission(PermissionLevel.WRITE)
     async def set_user_status(
         status_type: str = "",
@@ -102,7 +103,7 @@ async def set_user_status(
             )
         return json.dumps(_format_status(result), indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE_IDEMPOTENT)
     @require_permission(PermissionLevel.WRITE)
     async def clear_user_status() -> str:
         """Clear the current user's status message and icon.

src/nextcloud_mcp/tools/users.py

@@ -4,12 +4,13 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from ..annotations import ADDITIVE, DESTRUCTIVE, READONLY
 from ..permissions import PermissionLevel, require_permission
 from ..state import get_client
 
 
 def _register_read_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def get_current_user() -> str:
         """Get information about the currently authenticated Nextcloud user.
@@ -21,7 +22,7 @@ async def get_current_user() -> str:
         data = await client.ocs_get("cloud/user")
         return json.dumps(data, indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def list_users(search: str = "", limit: int = 25, offset: int = 0) -> str:
         """List Nextcloud users.
@@ -39,7 +40,7 @@ async def list_users(search: str = "", limit: int = 25, offset: int = 0) -> str:
         data = await client.ocs_get("cloud/users", params=params)
         return json.dumps(data, indent=2, default=str)
 
-    @mcp.tool()
+    @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
     async def get_user(user_id: str) -> str:
         """Get detailed information about a specific Nextcloud user.
@@ -56,7 +57,7 @@ async def get_user(user_id: str) -> str:
 
 
 def _register_write_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=ADDITIVE)
     @require_permission(PermissionLevel.WRITE)
     async def create_user(user_id: str, password: str, display_name: str = "", email: str = "") -> str:
         """Create a new Nextcloud user. Requires admin privileges.
@@ -81,7 +82,7 @@ async def create_user(user_id: str, password: str, display_name: str = "", email
 
 
 def _register_destructive_tools(mcp: FastMCP) -> None:
-    @mcp.tool()
+    @mcp.tool(annotations=DESTRUCTIVE)
     @require_permission(PermissionLevel.DESTRUCTIVE)
     async def delete_user(user_id: str) -> str:
         """Permanently delete a Nextcloud user. Requires admin privileges.

tests/integration/test_server.py

@@ -66,6 +66,13 @@ async def test_every_tool_has_description(self, nc_config: Config) -> None:
             assert tool.description, f"Tool '{tool.name}' has no description"
             assert len(tool.description) > 20, f"Tool '{tool.name}' description too short"
 
+    @pytest.mark.asyncio
+    async def test_every_tool_has_annotations(self, nc_config: Config) -> None:
+        mcp = create_server(nc_config)
+        for tool in mcp._tool_manager.list_tools():
+            assert tool.annotations is not None, f"Tool '{tool.name}' has no annotations"
+            assert tool.annotations.readOnlyHint is not None, f"Tool '{tool.name}' missing readOnlyHint"
+
     @pytest.mark.asyncio
     async def test_server_name(self, nc_config: Config) -> None:
         mcp = create_server(nc_config)