Add upload_file_binary tool for base64-encoded binary uploads (#44)

Author: oleksandr-nc

PROGRESS.md

@@ -37,6 +37,7 @@
 - [x] Contacts tools: list_addressbooks, get_contacts, get_contact, create_contact, update_contact, delete_contact (2026-03-31)
 - [x] Tasks tools: list_task_lists, get_tasks, get_task, create_task, update_task, complete_task, delete_task (2026-04-08)
 - [x] Unified Search tools: list_search_providers, unified_search (2026-04-12)
+- [x] upload_file_binary tool: base64-encoded binary upload with MIME inference (2026-04-21)
 
 ### In Progress
 
@@ -62,7 +63,7 @@
 
 | Module | Tools | Tests |
 |--------|-------|-------|
-| Files | 8 | 47 |
+| Files | 9 | 60 |
 | Users | 5 | 20 |
 | Notifications | 3 | 11 |
 | Talk | 8 | 48 |
@@ -89,4 +90,5 @@
 | Client | — | 29 |
 | Config | — | 17 |
 | State | — | 2 |
-| **Total** | **97** | **687** |
+| File Helpers | — | 11 |
+| **Total** | **98** | **711** |

README.md

@@ -30,11 +30,11 @@ export NEXTCLOUD_PASSWORD=your-app-password
 nc-mcp-server
 ```
 
-## 88 Tools Across 18 Nextcloud Apps
+## 98 Tools Across 20 Nextcloud Apps
 
 | Category | Tools | Protocol |
 |----------|-------|----------|
-| [Files](#files) | list, read, search, upload, copy, move, delete | WebDAV |
+| [Files](#files) | list, read, search, upload (text + binary), copy, move, delete | WebDAV |
 | [File Sharing](#file-sharing) | list, get, create, update, delete shares | OCS |
 | [Trashbin](#trashbin) | list, restore, delete item, empty trash | WebDAV |
 | [File Versions](#file-versions) | list, restore versions | WebDAV |
@@ -49,8 +49,10 @@ nc-mcp-server
 | [Announcements](#announcements) | list, create, delete announcements | OCS |
 | [Calendar](#calendar) | list calendars, CRUD events | CalDAV |
 | [Contacts](#contacts) | list address books, CRUD contacts | CardDAV |
+| [Tasks](#tasks) | list lists, CRUD tasks, complete | CalDAV |
 | [Mail](#mail) | accounts, mailboxes, messages, send | REST |
 | [Collectives](#collectives) | list, pages, create, trash, restore | REST |
+| [Unified Search](#unified-search) | list providers, search across apps | OCS |
 | [App Management](#app-management) | list, info, enable, disable apps | OCS |
 
 ## Security: Permission Model
@@ -163,7 +165,8 @@ nc-mcp-server
 | `list_directory` | read | List files and folders in a directory |
 | `get_file` | read | Read a file's content (returns images as MCP ImageContent) |
 | `search_files` | read | Search files by name, MIME type, or path pattern |
-| `upload_file` | write | Upload or overwrite a file |
+| `upload_file` | write | Upload or overwrite a text file |
+| `upload_file_binary` | write | Upload or overwrite a binary file (images, PDFs, archives) from base64-encoded content |
 | `create_directory` | write | Create a new directory |
 | `copy_file` | write | Copy a file or directory |
 | `move_file` | destructive | Move or rename a file |
@@ -299,6 +302,18 @@ nc-mcp-server
 | `update_contact` | write | Update a contact (ETag concurrency control) |
 | `delete_contact` | destructive | Delete a contact |
 
+### Tasks
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `list_task_lists` | read | List task lists (CalDAV VTODO collections) |
+| `get_tasks` | read | List tasks in a list (with status/completed filters) |
+| `get_task` | read | Get a single task by UID |
+| `create_task` | write | Create a task (due date, priority, categories, etc.) |
+| `update_task` | write | Update a task (partial updates supported) |
+| `complete_task` | write | Mark a task as completed |
+| `delete_task` | destructive | Delete a task |
+
 ### Mail
 
 | Tool | Permission | Description |
@@ -325,6 +340,13 @@ nc-mcp-server
 | `restore_collective` | write | Restore a collective from trash |
 | `restore_collective_page` | write | Restore a page from trash |
 
+### Unified Search
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `list_search_providers` | read | List available search providers (files, mail, talk, etc.) |
+| `unified_search` | read | Search across one or more providers with pagination |
+
 ### App Management
 
 | Tool | Permission | Description |

src/nc_mcp_server/tools/files.py

@@ -1,7 +1,9 @@
 """File management tools — list, read, upload, copy, delete, move, search files via WebDAV."""
 
 import base64
+import binascii
 import json
+import mimetypes
 from xml.sax.saxutils import escape as xml_escape
 
 from mcp.server.fastmcp import FastMCP
@@ -21,6 +23,13 @@
 _MAX_IMAGE_SIZE = 10 * 1024 * 1024
 
 
+def _resolve_content_type(path: str, content_type: str) -> str:
+    if content_type.strip():
+        return content_type.strip()
+    guessed, _ = mimetypes.guess_type(path)
+    return guessed or "application/octet-stream"
+
+
 def _build_search_xml(user: str, query: str, path: str, limit: int, offset: int, mimetype: str) -> str:
     """Build a WebDAV SEARCH request body."""
     where_parts: list[str] = []
@@ -181,6 +190,9 @@ def _register_write_tools(mcp: FastMCP) -> None:
     async def upload_file(path: str, content: str) -> str:
         """Upload or overwrite a text file in Nextcloud.
 
+        Use this for plain-text content (markdown, source code, CSV, JSON, etc.).
+        For binary files (images, PDFs, archives), use upload_file_binary instead.
+
         Creates the file if it doesn't exist. Overwrites if it does.
 
         Args:
@@ -194,6 +206,39 @@ 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(annotations=ADDITIVE_IDEMPOTENT)
+    @require_permission(PermissionLevel.WRITE)
+    async def upload_file_binary(path: str, content_base64: str, content_type: str = "") -> str:
+        """Upload or overwrite a binary file in Nextcloud.
+
+        Use this for images, PDFs, archives, or any non-text content. The content
+        must be base64-encoded. For plain-text files, use upload_file instead.
+
+        Creates the file if it doesn't exist. Overwrites if it does.
+
+        Args:
+            path: Destination path relative to user's root. Example: "Photos/photo.png"
+            content_base64: File bytes encoded as a base64 string. May be empty to
+                create an empty file.
+            content_type: MIME type for the upload request (e.g. "image/png",
+                "application/pdf"). If omitted, inferred from the path extension;
+                falls back to "application/octet-stream". Note: Nextcloud re-derives
+                the stored MIME type from the filename, so this mainly controls the
+                HTTP upload header.
+
+        Returns:
+            Confirmation message with the uploaded byte count.
+        """
+        cleaned = "".join(content_base64.split()) if content_base64 else ""
+        try:
+            data = base64.b64decode(cleaned, validate=True) if cleaned else b""
+        except (binascii.Error, ValueError) as exc:
+            raise ValueError(f"content_base64 is not valid base64: {exc}") from exc
+        resolved = _resolve_content_type(path, content_type)
+        client = get_client()
+        await client.dav_put(path, data, content_type=resolved)
+        return f"File uploaded successfully: {path} ({len(data)} bytes, {resolved})"
+
     @mcp.tool(annotations=ADDITIVE_IDEMPOTENT)
     @require_permission(PermissionLevel.WRITE)
     async def copy_file(source: str, destination: str) -> str:

tests/integration/test_files.py

@@ -139,6 +139,181 @@ async def test_upload_large_text(self, nc_mcp: McpTestHelper) -> None:
         assert len(result) == 100_000
 
 
+class TestUploadFileBinary:
+    """Binary upload round-trips through Nextcloud. Payloads are fetched back with
+    raw WebDAV (bypassing `get_file`) so we can assert byte-for-byte equality.
+    """
+
+    @pytest.mark.asyncio
+    async def test_upload_png_round_trip(self, nc_mcp: McpTestHelper) -> None:
+        await nc_mcp.create_test_dir()
+        await nc_mcp.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/pixel.png",
+            content_base64=_TINY_PNG_B64,
+            content_type="image/png",
+        )
+        got, ct = await nc_mcp.client.dav_get(f"{TEST_BASE_DIR}/pixel.png")
+        assert got == _TINY_PNG
+        assert ct == "image/png"
+
+    @pytest.mark.asyncio
+    async def test_upload_pdf_round_trip(self, nc_mcp: McpTestHelper) -> None:
+        await nc_mcp.create_test_dir()
+        pdf_bytes = (
+            b"%PDF-1.4\n"
+            b"1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj\n"
+            b"2 0 obj<</Type/Pages/Count 0/Kids[]>>endobj\n"
+            b"xref\n0 3\n0000000000 65535 f\n"
+            b"0000000009 00000 n\n0000000052 00000 n\n"
+            b"trailer<</Size 3/Root 1 0 R>>\nstartxref\n91\n%%EOF\n"
+        )
+        pdf_b64 = base64.b64encode(pdf_bytes).decode("ascii")
+        await nc_mcp.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/sample.pdf",
+            content_base64=pdf_b64,
+        )
+        got, ct = await nc_mcp.client.dav_get(f"{TEST_BASE_DIR}/sample.pdf")
+        assert got == pdf_bytes
+        assert ct == "application/pdf"
+
+    @pytest.mark.asyncio
+    async def test_upload_full_byte_range(self, nc_mcp: McpTestHelper) -> None:
+        """Bytes 0x00-0xFF cover the full range that plain upload_file cannot send."""
+        await nc_mcp.create_test_dir()
+        raw = bytes(range(256)) * 8  # 2 KiB of every byte value
+        b64 = base64.b64encode(raw).decode("ascii")
+        await nc_mcp.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/all-bytes.bin",
+            content_base64=b64,
+            content_type="application/octet-stream",
+        )
+        got, _ = await nc_mcp.client.dav_get(f"{TEST_BASE_DIR}/all-bytes.bin")
+        assert got == raw
+
+    @pytest.mark.asyncio
+    async def test_content_type_inferred_from_extension(self, nc_mcp: McpTestHelper) -> None:
+        await nc_mcp.create_test_dir()
+        await nc_mcp.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/auto.png",
+            content_base64=_TINY_PNG_B64,
+        )
+        _, ct = await nc_mcp.client.dav_get(f"{TEST_BASE_DIR}/auto.png")
+        assert ct == "image/png"
+
+    @pytest.mark.asyncio
+    async def test_overwrites_existing_file(self, nc_mcp: McpTestHelper) -> None:
+        await nc_mcp.create_test_dir()
+        first = base64.b64encode(b"first-version").decode("ascii")
+        second = base64.b64encode(b"second-version-longer").decode("ascii")
+        await nc_mcp.call("upload_file_binary", path=f"{TEST_BASE_DIR}/ow.bin", content_base64=first)
+        await nc_mcp.call("upload_file_binary", path=f"{TEST_BASE_DIR}/ow.bin", content_base64=second)
+        got, _ = await nc_mcp.client.dav_get(f"{TEST_BASE_DIR}/ow.bin")
+        assert got == b"second-version-longer"
+
+    @pytest.mark.asyncio
+    async def test_empty_content_creates_empty_file(self, nc_mcp: McpTestHelper) -> None:
+        await nc_mcp.create_test_dir()
+        await nc_mcp.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/empty.bin",
+            content_base64="",
+            content_type="application/octet-stream",
+        )
+        got, _ = await nc_mcp.client.dav_get(f"{TEST_BASE_DIR}/empty.bin")
+        assert got == b""
+
+    @pytest.mark.asyncio
+    async def test_result_message_reports_bytes_and_type(self, nc_mcp: McpTestHelper) -> None:
+        await nc_mcp.create_test_dir()
+        result = await nc_mcp.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/reported.png",
+            content_base64=_TINY_PNG_B64,
+            content_type="image/png",
+        )
+        assert str(len(_TINY_PNG)) in result
+        assert "image/png" in result
+
+    @pytest.mark.asyncio
+    async def test_invalid_base64_raises(self, nc_mcp: McpTestHelper) -> None:
+        await nc_mcp.create_test_dir()
+        with pytest.raises(ToolError, match=r"not valid base64"):
+            await nc_mcp.call(
+                "upload_file_binary",
+                path=f"{TEST_BASE_DIR}/bad.bin",
+                content_base64="!!!not-base64!!!",
+            )
+
+    @pytest.mark.asyncio
+    async def test_mime_wrapped_base64_accepted(self, nc_mcp: McpTestHelper) -> None:
+        """MIME-style base64 (76-char line wraps with \\r\\n) should decode cleanly."""
+        await nc_mcp.create_test_dir()
+        raw = bytes(range(200))
+        wrapped = base64.encodebytes(raw).decode("ascii")  # always adds \n every 76 chars
+        assert "\n" in wrapped
+        await nc_mcp.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/wrapped.bin",
+            content_base64=wrapped,
+        )
+        got, _ = await nc_mcp.client.dav_get(f"{TEST_BASE_DIR}/wrapped.bin")
+        assert got == raw
+
+    @pytest.mark.asyncio
+    async def test_base64_with_stray_whitespace_accepted(self, nc_mcp: McpTestHelper) -> None:
+        await nc_mcp.create_test_dir()
+        raw = b"payload with stray whitespace"
+        encoded = base64.b64encode(raw).decode("ascii")
+        dirty = f"  {encoded[:10]} \t \n{encoded[10:]}\r\n"
+        await nc_mcp.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/dirty.bin",
+            content_base64=dirty,
+        )
+        got, _ = await nc_mcp.client.dav_get(f"{TEST_BASE_DIR}/dirty.bin")
+        assert got == raw
+
+    @pytest.mark.asyncio
+    async def test_uploaded_image_readable_via_get_file(self, nc_mcp: McpTestHelper) -> None:
+        """Binary upload integrates with existing get_file image handling."""
+        await nc_mcp.create_test_dir()
+        await nc_mcp.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/readable.png",
+            content_base64=_TINY_PNG_B64,
+        )
+        result = await nc_mcp.mcp._tool_manager.call_tool("get_file", {"path": f"{TEST_BASE_DIR}/readable.png"})
+        assert isinstance(result, list)
+        item = result[0]  # type: ignore[index]
+        assert item.type == "image"  # type: ignore[union-attr]
+        assert item.mimeType == "image/png"  # type: ignore[union-attr]
+        assert base64.b64decode(item.data) == _TINY_PNG  # type: ignore[union-attr]
+
+    @pytest.mark.asyncio
+    async def test_read_only_blocks(self, nc_mcp_read_only: McpTestHelper) -> None:
+        with pytest.raises(ToolError, match=r"[Pp]ermission"):
+            await nc_mcp_read_only.call(
+                "upload_file_binary",
+                path=f"{TEST_BASE_DIR}/denied.png",
+                content_base64=_TINY_PNG_B64,
+            )
+
+    @pytest.mark.asyncio
+    async def test_write_permission_allows(self, nc_mcp_write: McpTestHelper) -> None:
+        await nc_mcp_write.create_test_dir()
+        result = await nc_mcp_write.call(
+            "upload_file_binary",
+            path=f"{TEST_BASE_DIR}/write-ok.png",
+            content_base64=_TINY_PNG_B64,
+            content_type="image/png",
+        )
+        assert "uploaded successfully" in result
+
+
 class TestCreateDirectory:
     @pytest.mark.asyncio
     async def test_create_directory(self, nc_mcp: McpTestHelper) -> None:

tests/integration/test_server.py

@@ -105,6 +105,7 @@
     "update_share",
     "update_task",
     "upload_file",
+    "upload_file_binary",
     "vote_poll",
 ]
 

tests/test_files_helpers.py

@@ -0,0 +1,39 @@
+"""Unit tests for pure helpers in tools.files."""
+
+from nc_mcp_server.tools.files import _resolve_content_type
+
+
+class TestResolveContentType:
+    def test_explicit_content_type_kept(self) -> None:
+        assert _resolve_content_type("photo.png", "custom/type") == "custom/type"
+
+    def test_explicit_content_type_kept_for_unknown_extension(self) -> None:
+        assert _resolve_content_type("blob.weirdext", "application/x-custom") == "application/x-custom"
+
+    def test_png_extension_inferred(self) -> None:
+        assert _resolve_content_type("photo.png", "") == "image/png"
+
+    def test_pdf_extension_inferred(self) -> None:
+        assert _resolve_content_type("doc.pdf", "") == "application/pdf"
+
+    def test_jpeg_extension_inferred(self) -> None:
+        assert _resolve_content_type("photo.jpeg", "") == "image/jpeg"
+
+    def test_unknown_extension_falls_back(self) -> None:
+        assert _resolve_content_type("blob.weirdext", "") == "application/octet-stream"
+
+    def test_no_extension_falls_back(self) -> None:
+        assert _resolve_content_type("noext", "") == "application/octet-stream"
+
+    def test_nested_path_inference(self) -> None:
+        assert _resolve_content_type("deep/sub/path/photo.png", "") == "image/png"
+
+    def test_whitespace_only_content_type_falls_back_to_inference(self) -> None:
+        assert _resolve_content_type("photo.png", "   ") == "image/png"
+        assert _resolve_content_type("photo.png", "\t\n") == "image/png"
+
+    def test_whitespace_only_content_type_falls_back_to_octet_stream(self) -> None:
+        assert _resolve_content_type("blob.weirdext", "   ") == "application/octet-stream"
+
+    def test_explicit_content_type_trimmed(self) -> None:
+        assert _resolve_content_type("photo.png", "  image/png  ") == "image/png"