Add Files Sharing tools: list_shares, get_share, create_share, update_share, delete_share

bigcat88 · bigcat88 · commit 195648a2568c · 2026-03-26T08:28:49.000Z
diff --git a/PROGRESS.md b/PROGRESS.md
@@ -24,6 +24,7 @@
 - [x] copy_file tool via WebDAV COPY (2026-03-25)
 - [x] get_file returns MCP ImageContent for images (PNG, JPEG, GIF, WebP, BMP, SVG) (2026-03-25)
 - [x] System Tags tools: list_tags, get_file_tags, create_tag, assign_tag, unassign_tag, delete_tag (2026-03-25)
+- [x] Files Sharing tools: list_shares, get_share, create_share, update_share, delete_share (2026-03-26)
 
 ### In Progress
 
@@ -32,7 +33,7 @@
 
 ### Next Up
 - Announcement Center
-- Files Sharing, Trashbin, Versions
+- Files Trashbin, Versions
 - Improve error handling and error messages
 
 ## Phases
@@ -61,5 +62,6 @@
 | Errors | — | 10 |
 | Config | — | 12 |
 | State | — | 2 |
+| Shares | 5 | 33 |
 | System Tags | 6 | 22 |
-| **Total** | **42** | **313** |
+| **Total** | **47** | **349** |
diff --git a/src/nextcloud_mcp/server.py b/src/nextcloud_mcp/server.py
@@ -11,6 +11,7 @@
     comments,
     files,
     notifications,
+    shares,
     system_tags,
     talk,
     user_status,
@@ -47,6 +48,7 @@ def create_server(config: Config | None = None) -> FastMCP:
     comments.register(mcp)
     files.register(mcp)
     notifications.register(mcp)
+    shares.register(mcp)
     system_tags.register(mcp)
     talk.register(mcp)
     user_status.register(mcp)
diff --git a/src/nextcloud_mcp/tools/shares.py b/src/nextcloud_mcp/tools/shares.py
@@ -0,0 +1,224 @@
+"""File sharing tools — list, get, create, update, and delete shares via OCS API."""
+
+import json
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from ..annotations import ADDITIVE, DESTRUCTIVE, READONLY
+from ..permissions import PermissionLevel, require_permission
+from ..state import get_client
+
+SHARES_API = "apps/files_sharing/api/v1/shares"
+
+
+def _format_share(share: dict[str, Any]) -> dict[str, Any]:
+    """Extract the most useful fields from a raw share object."""
+    result: dict[str, Any] = {
+        "id": share.get("id"),
+        "share_type": share.get("share_type"),
+        "path": share.get("path"),
+        "item_type": share.get("item_type"),
+        "permissions": share.get("permissions"),
+        "uid_owner": share.get("uid_owner"),
+        "share_with": share.get("share_with"),
+        "share_with_displayname": share.get("share_with_displayname"),
+        "expiration": share.get("expiration"),
+        "note": share.get("note"),
+        "label": share.get("label"),
+    }
+    if share.get("token"):
+        result["token"] = share["token"]
+    if share.get("url"):
+        result["url"] = share["url"]
+    if share.get("password"):
+        result["has_password"] = True
+    if share.get("hide_download"):
+        result["hide_download"] = share["hide_download"]
+    return result
+
+
+def _register_read_tools(mcp: FastMCP) -> None:
+    @mcp.tool(annotations=READONLY)
+    @require_permission(PermissionLevel.READ)
+    async def list_shares(
+        path: str = "",
+        reshares: bool = False,
+        subfiles: bool = False,
+    ) -> str:
+        """List file/folder shares from Nextcloud.
+
+        Without arguments, returns all shares owned by the current user.
+        With a path, returns shares for that specific file or folder.
+
+        Args:
+            path: Optional file/folder path to filter shares (e.g. "/Documents/report.pdf").
+            reshares: If true, include shares by other users on the same files.
+            subfiles: If true and path is a folder, list shares of files inside it (not the folder itself).
+
+        Returns:
+            JSON list of share objects with: id, share_type, path, permissions, share_with, etc.
+            share_type values: 0=user, 1=group, 3=public link, 4=email, 6=federated, 10=talk room.
+        """
+        client = get_client()
+        params: dict[str, str] = {}
+        if path:
+            params["path"] = path
+        if reshares:
+            params["reshares"] = "true"
+        if subfiles:
+            params["subfiles"] = "true"
+        data = await client.ocs_get(SHARES_API, params=params)
+        shares = [_format_share(s) for s in data]
+        return json.dumps(shares, indent=2, default=str)
+
+    @mcp.tool(annotations=READONLY)
+    @require_permission(PermissionLevel.READ)
+    async def get_share(share_id: int) -> str:
+        """Get details of a specific share by its ID.
+
+        Args:
+            share_id: The numeric share ID.
+
+        Returns:
+            JSON object with share details: id, share_type, path, permissions, share_with,
+            url (for link shares), expiration, note, label, etc.
+        """
+        client = get_client()
+        data = await client.ocs_get(f"{SHARES_API}/{share_id}")
+        share = _format_share(data[0])
+        return json.dumps(share, indent=2, default=str)
+
+
+def _register_create_share(mcp: FastMCP) -> None:
+    @mcp.tool(annotations=ADDITIVE)
+    @require_permission(PermissionLevel.WRITE)
+    async def create_share(
+        path: str,
+        share_type: int,
+        share_with: str = "",
+        permissions: int = 0,
+        password: str = "",
+        expire_date: str = "",
+        note: str = "",
+        label: str = "",
+        public_upload: bool = False,
+    ) -> str:
+        """Create a new share for a file or folder.
+
+        Args:
+            path: Path to the file or folder to share (e.g. "/Documents/report.pdf").
+            share_type: Type of share: 0=user, 1=group, 3=public link, 4=email, 6=federated, 10=talk room.
+            share_with: Recipient — required for all types except link (3).
+                User share (0): username. Group share (1): group name.
+                Email share (4): email address. Federated (6): user@remote.server.
+                Talk room (10): room token.
+            permissions: Bitwise permission flags. 1=read, 2=update, 4=create, 8=delete, 16=share.
+                Common values: 1 (read-only), 15 (full, no reshare), 31 (all).
+                Default: all permissions (31) for user/group, read-only (1) for links.
+                Note: file shares automatically strip create (4) and delete (8) flags.
+            password: Optional password for link (3) or email (4) shares.
+            expire_date: Optional expiration date in "YYYY-MM-DD" format.
+            note: Optional note/message for the share recipient.
+            label: Optional display label for link shares (max 255 chars).
+            public_upload: Enable public upload on shared folders (link shares only).
+
+        Returns:
+            JSON object with the created share details including id, url (for links), token, etc.
+        """
+        client = get_client()
+        data: dict[str, str | int] = {"path": path, "shareType": share_type}
+        if share_with:
+            data["shareWith"] = share_with
+        if permissions > 0:
+            data["permissions"] = permissions
+        if password:
+            data["password"] = password
+        if expire_date:
+            data["expireDate"] = expire_date
+        if note:
+            data["note"] = note
+        if label:
+            data["label"] = label
+        if public_upload:
+            data["publicUpload"] = "true"
+        result = await client.ocs_post(SHARES_API, data=data)
+        return json.dumps(_format_share(result), indent=2, default=str)
+
+
+def _register_update_share(mcp: FastMCP) -> None:
+    @mcp.tool(annotations=ADDITIVE)
+    @require_permission(PermissionLevel.WRITE)
+    async def update_share(
+        share_id: int,
+        permissions: int = 0,
+        password: str = "",
+        expire_date: str = "",
+        note: str = "",
+        label: str = "",
+        public_upload: bool = False,
+        hide_download: bool = False,
+    ) -> str:
+        """Update properties of an existing share.
+
+        Only provided (non-default) parameters are changed. To remove a password or
+        expiration, use delete_share and create a new one.
+
+        Args:
+            share_id: The numeric share ID to update.
+            permissions: New permission flags (1=read, 2=update, 4=create, 8=delete, 16=share).
+            password: Set or change password (link/email shares only).
+            expire_date: Set expiration date in "YYYY-MM-DD" format.
+            note: Set or update the share note.
+            label: Set or update the share label.
+            public_upload: Enable/disable public upload on shared folders (link shares only).
+            hide_download: Hide the download button on public link shares.
+
+        Returns:
+            JSON object with the updated share details.
+        """
+        client = get_client()
+        data: dict[str, str | int] = {}
+        if permissions > 0:
+            data["permissions"] = permissions
+        if password:
+            data["password"] = password
+        if expire_date:
+            data["expireDate"] = expire_date
+        if note:
+            data["note"] = note
+        if label:
+            data["label"] = label
+        if public_upload:
+            data["publicUpload"] = "true"
+        if hide_download:
+            data["hideDownload"] = "true"
+        result = await client.ocs_put(f"{SHARES_API}/{share_id}", data=data)
+        return json.dumps(_format_share(result), indent=2, default=str)
+
+
+def _register_destructive_tools(mcp: FastMCP) -> None:
+    @mcp.tool(annotations=DESTRUCTIVE)
+    @require_permission(PermissionLevel.DESTRUCTIVE)
+    async def delete_share(share_id: int) -> str:
+        """Delete (unshare) a share by its ID.
+
+        This revokes access for the share recipient. The file/folder itself is not deleted.
+
+        Args:
+            share_id: The numeric share ID to delete. Use list_shares to find share IDs.
+
+        Returns:
+            Confirmation message.
+        """
+        client = get_client()
+        await client.ocs_delete(f"{SHARES_API}/{share_id}")
+        return f"Share {share_id} deleted."
+
+
+def register(mcp: FastMCP) -> None:
+    """Register file sharing tools with the MCP server."""
+    _register_read_tools(mcp)
+    _register_create_share(mcp)
+    _register_update_share(mcp)
+    _register_destructive_tools(mcp)
diff --git a/tests/integration/conftest.py b/tests/integration/conftest.py
@@ -139,6 +139,11 @@ async def _clean_test_data(_cleanup_config: Config) -> AsyncGenerator[None]:
 
 async def _cleanup(client: NextcloudClient) -> None:
     """Remove all test artifacts from Nextcloud."""
+    with contextlib.suppress(Exception):
+        shares = await client.ocs_get("apps/files_sharing/api/v1/shares")
+        for share in shares:
+            with contextlib.suppress(Exception):
+                await client.ocs_delete(f"apps/files_sharing/api/v1/shares/{share['id']}")
     with contextlib.suppress(Exception):
         await client.dav_delete(TEST_BASE_DIR)
     with contextlib.suppress(Exception):
diff --git a/tests/integration/test_server.py b/tests/integration/test_server.py
@@ -17,11 +17,13 @@
     "create_conversation",
     "create_directory",
     "create_poll",
+    "create_share",
     "create_tag",
     "create_user",
     "delete_comment",
     "delete_file",
     "delete_message",
+    "delete_share",
     "delete_tag",
     "delete_user",
     "dismiss_all_notifications",
@@ -35,20 +37,23 @@
     "get_messages",
     "get_participants",
     "get_poll",
+    "get_share",
     "get_user",
     "get_user_status",
     "leave_conversation",
     "list_comments",
     "list_conversations",
     "list_directory",
     "list_notifications",
+    "list_shares",
     "list_tags",
     "list_users",
     "move_file",
     "search_files",
     "send_message",
     "set_user_status",
     "unassign_tag",
+    "update_share",
     "upload_file",
     "vote_poll",
 ]
diff --git a/tests/integration/test_shares.py b/tests/integration/test_shares.py
