Add Forms tools — full OCS v3 coverage (25 tools) (#47)

Author: oleksandr-nc

.github/workflows/tests-integration.yml

@@ -72,6 +72,7 @@ jobs:
           $OCC "php occ app:install announcementcenter" || echo "announcementcenter already installed"
           $OCC "php occ app:install collectives" || echo "collectives already installed"
           $OCC "php occ app:install mail"
+          $OCC "php occ app:install forms" || echo "forms already installed"
           SMTP4DEV_IP=$(docker inspect ${{ job.services.smtp4dev.id }} --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}')
           echo "smtp4dev IP: $SMTP4DEV_IP"
           $OCC "php occ mail:account:create admin 'Test Mail' test@localhost $SMTP4DEV_IP 143 none test test $SMTP4DEV_IP 25 none test test"

PROGRESS.md

@@ -40,14 +40,15 @@
 - [x] upload_file_binary tool: base64-encoded binary upload with MIME inference (2026-04-21)
 - [x] upload_file_from_path tool: stream a local file to Nextcloud. Off by default; enabled via NEXTCLOUD_MCP_UPLOAD_ROOT, restricted to files inside that root (symlinks resolved) (2026-04-21)
 - [x] File Reminders tools: get_file_reminder, set_file_reminder, remove_file_reminder (2026-04-22)
+- [x] Forms tools: 25 tools covering forms, questions, options, shares, submissions CRUD + export (2026-04-23)
 
 ### In Progress
 
 ### Blocked
 (none)
 
 ### Next Up
-- Tables, Forms, Weather Status (all with full OCS coverage)
+- Weather Status (fully OCS). Tables skipped for now — OCS v2 API is incomplete (rows/columns/views require v1 REST).
 
 ## Phases
 
@@ -94,7 +95,8 @@
 | State | — | 2 |
 | File Helpers | — | 26 |
 | File Reminders | 3 | 20 |
-| **Total** | **102** | **771** |
+| Forms | 25 | 34 |
+| **Total** | **127** | **805** |
 
 Files shows 10, but one (`upload_file_from_path`) is only registered when
-`NEXTCLOUD_MCP_UPLOAD_ROOT` is configured. Default deployments expose 101 tools.
+`NEXTCLOUD_MCP_UPLOAD_ROOT` is configured. Default deployments expose 126 tools.

README.md

@@ -30,9 +30,9 @@ export NEXTCLOUD_PASSWORD=your-app-password
 nc-mcp-server
 ```
 
-## 101 Tools Across 21 Nextcloud Apps
+## 126 Tools Across 22 Nextcloud Apps
 
-A 102nd tool, `upload_file_from_path`, is registered only when the operator sets
+A 127th tool, `upload_file_from_path`, is registered only when the operator sets
 `NEXTCLOUD_MCP_UPLOAD_ROOT`. See [Files](#files) for details.
 
 | Category | Tools | Protocol |
@@ -56,6 +56,7 @@ A 102nd tool, `upload_file_from_path`, is registered only when the operator sets
 | [Tasks](#tasks) | list lists, CRUD tasks, complete | CalDAV |
 | [Mail](#mail) | accounts, mailboxes, messages, send | REST |
 | [Collectives](#collectives) | list, pages, create, trash, restore | REST |
+| [Forms](#forms) | CRUD forms, questions, options, shares, submissions + export | OCS |
 | [Unified Search](#unified-search) | list providers, search across apps | OCS |
 | [App Management](#app-management) | list, info, enable, disable apps | OCS |
 
@@ -363,6 +364,36 @@ call; the body is streamed in chunks rather than loaded into memory.
 | `restore_collective` | write | Restore a collective from trash |
 | `restore_collective_page` | write | Restore a page from trash |
 
+### Forms
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `list_forms` | read | List forms (filter by ownership: "owned" or "shared"; omit to merge both) |
+| `get_form` | read | Get a form with questions, options, shares |
+| `list_questions` | read | List questions on a form |
+| `get_question` | read | Get a single question |
+| `list_submissions` | read | List submissions (owner only), with pagination and text filter |
+| `get_submission` | read | Get a single submission with answers |
+| `create_form` | write | Create an empty form or clone from an existing form |
+| `update_form` | write | Update form properties (title, access, state, maxSubmissions, etc.) |
+| `create_question` | write | Add a question (short, long, multiple, dropdown, date, file, grid, …) |
+| `update_question` | write | Update question properties |
+| `reorder_questions` | write | Reorder all questions on a form |
+| `create_options` | write | Add answer options to a choice question |
+| `update_option` | write | Update option text |
+| `reorder_options` | write | Reorder options within a question |
+| `create_form_share` | write | Share a form with user, group, circle, or link |
+| `update_form_share` | write | Update share permissions |
+| `submit_form` | write | Submit answers to a form |
+| `update_submission` | write | Edit an existing submission (requires allowEditSubmissions) |
+| `export_submissions` | write | Export submissions as a spreadsheet to a Nextcloud folder |
+| `delete_form` | destructive | Delete a form and all its content |
+| `delete_question` | destructive | Delete a question |
+| `delete_option` | destructive | Delete an option |
+| `delete_form_share` | destructive | Revoke a share |
+| `delete_submission` | destructive | Delete one submission |
+| `delete_all_submissions` | destructive | Delete every submission on a form |
+
 ### Unified Search
 
 | Tool | Permission | Description |

src/nc_mcp_server/client.py

@@ -271,6 +271,22 @@ async def ocs_patch(self, path: str, data: dict[str, Any] | None = None) -> Any:
         result: dict[str, Any] = response.json()  # type: ignore[assignment]
         return result["ocs"]["data"]
 
+    async def ocs_patch_json(self, path: str, json_data: dict[str, Any] | None = None) -> Any:
+        """Make an OCS PATCH request with a JSON body and return the data portion."""
+        url = f"{self._base_url}/ocs/v2.php/{path}"
+        response = await self._do_request("PATCH", url, json=json_data or {})
+        _raise_for_ocs_status(response, f"OCS PATCH {path}")
+        result: dict[str, Any] = response.json()  # type: ignore[assignment]
+        return result["ocs"]["data"]
+
+    async def ocs_put_json(self, path: str, json_data: dict[str, Any] | None = None) -> Any:
+        """Make an OCS PUT request with a JSON body and return the data portion."""
+        url = f"{self._base_url}/ocs/v2.php/{path}"
+        response = await self._do_request("PUT", url, json=json_data or {})
+        _raise_for_ocs_status(response, f"OCS PUT {path}")
+        result: dict[str, Any] = response.json()  # type: ignore[assignment]
+        return result["ocs"]["data"]
+
     # --- WebDAV ---
 
     async def dav_propfind(self, path: str, depth: int = 1) -> list[dict[str, Any]]:

src/nc_mcp_server/server.py

@@ -15,6 +15,7 @@
     comments,
     contacts,
     files,
+    forms,
     mail,
     notifications,
     reminders,
@@ -63,6 +64,7 @@ def create_server(config: Config | None = None) -> FastMCP:
     comments.register(mcp)
     contacts.register(mcp)
     files.register(mcp)
+    forms.register(mcp)
     mail.register(mcp)
     notifications.register(mcp)
     reminders.register(mcp)