Merge pull request #4 from cloud-py-api/feature/p2-talk-polls

Add Talk poll tools: get_poll, create_poll, vote_poll, close_poll

Author: oleksandr-nc

.github/workflows/ci.yml

@@ -61,7 +61,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        nextcloud-version: ["31", "32"]
+        nextcloud-version: ["32", "33"]
     services:
       nextcloud:
         image: nextcloud:${{ matrix.nextcloud-version }}

GUIDANCE.md

@@ -8,6 +8,7 @@ Rules and corrections for writing code in this project.
 - Never import inside functions. All imports must be at the top of the file.
 - Never use `# noqa: F401` — if something is imported, it must be used.
 - Maximum line length is 120 characters.
+- No decorative/separator comments (e.g. `# -----------` section banners). Code structure should be self-evident. Only add comments that explain *why*, never *what*.
 
 ## Tooling
 

PROGRESS.md

@@ -14,6 +14,7 @@
 - [x] Notifications tools: list_notifications, dismiss_notification, dismiss_all_notifications (2026-03-21)
 - [x] Test suite overhaul: MCP tool-level integration tests (2026-03-21)
 - [x] Talk tools: list_conversations, get_conversation, get_messages, get_participants, send_message, create_conversation, delete_message, leave_conversation (2026-03-22)
+- [x] Talk polls: get_poll, create_poll, vote_poll, close_poll (2026-03-24)
 
 ### In Progress
 - [ ] Activity tools: get_activity
@@ -23,7 +24,6 @@
 (none)
 
 ### Next Up
-- Talk polls: get_poll, create_poll, vote_poll
 - Announcement Center
 - Files Sharing, Trashbin, Versions
 - Improve error handling and error messages
@@ -39,13 +39,15 @@
 
 ## Test Coverage
 
-| Module | Tools | Integration Tests |
-|--------|-------|-------------------|
-| Files | 6 | 20 |
-| Users | 3 | 10 |
-| Notifications | 3 | 12 |
-| Talk | 8 | 44 |
+| Module | Tools | Tests |
+|--------|-------|-------|
+| Files | 6 | 24 |
+| Users | 3 | 13 |
+| Notifications | 3 | 11 |
+| Talk | 8 | 48 |
+| Talk Polls | 4 | 31 |
 | Server | — | 5 |
-| Permissions | — | 16 |
+| Permissions | — | 34 |
 | Errors | — | 10 |
-| **Total** | **20** | **127** |
+| Config | — | 12 |
+| **Total** | **24** | **188** |

src/nextcloud_mcp/client.py

@@ -106,12 +106,14 @@ async def ocs_post(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_delete(self, path: str) -> None:
-        """Make an OCS DELETE request."""
+    async def ocs_delete(self, path: str) -> Any:
+        """Make an OCS DELETE request and return the data portion (if any)."""
         session = await self._get_session()
         url = f"{self._base_url}/ocs/v2.php/{path}"
         response = await session.delete(url)
         _raise_for_status(response, f"OCS DELETE {path}")
+        result: dict[str, Any] = response.json()  # type: ignore[assignment]
+        return result["ocs"]["data"]
 
     # --- WebDAV ---
 

src/nextcloud_mcp/tools/talk.py

@@ -1,4 +1,4 @@
-"""Nextcloud Talk tools — conversations, messages, and participants via OCS API."""
+"""Nextcloud Talk tools — conversations, messages, participants, and polls via OCS API."""
 
 import json
 from typing import Any
@@ -32,6 +32,42 @@
 }
 
 
+# Poll status codes
+_POLL_STATUS: dict[int, str] = {
+    0: "open",
+    1: "closed",
+    2: "draft",
+}
+
+_RESULT_MODES: dict[int, str] = {
+    0: "public",
+    1: "hidden",
+}
+
+
+def _format_poll(poll: dict[str, Any]) -> dict[str, Any]:
+    """Extract the most useful fields from a raw poll object."""
+    result: dict[str, Any] = {
+        "id": poll["id"],
+        "question": poll["question"],
+        "options": poll.get("options", []),
+        "status": _POLL_STATUS.get(poll.get("status", 0), f"unknown({poll.get('status')})"),
+        "result_mode": _RESULT_MODES.get(poll.get("resultMode", 0), f"unknown({poll.get('resultMode')})"),
+        "max_votes": poll.get("maxVotes", 0),
+        "actor_id": poll.get("actorId", ""),
+        "actor_display_name": poll.get("actorDisplayName", ""),
+        "num_voters": poll.get("numVoters", 0),
+        "voted_self": poll.get("votedSelf", []),
+    }
+    votes = poll.get("votes")
+    if votes:
+        result["votes"] = votes
+    details = poll.get("details")
+    if details:
+        result["details"] = details
+    return result
+
+
 def _format_conversation(room: dict[str, Any]) -> dict[str, Any]:
     """Extract the most useful fields from a raw room object."""
     return {
@@ -200,9 +236,127 @@ 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()
+    @require_permission(PermissionLevel.READ)
+    async def get_poll(token: str, poll_id: int) -> str:
+        """Get a poll from a Talk conversation.
+
+        Returns poll details including question, options, current votes (if visible),
+        and which options the current user voted for.
+
+        Vote visibility depends on the poll's result_mode:
+        - "public": votes are visible after you vote.
+        - "hidden": votes are only visible after the poll is closed.
+
+        Args:
+            token: The conversation token. Use list_conversations to find tokens.
+            poll_id: The poll ID. Poll IDs appear in chat messages when a poll is created.
+
+        Returns:
+            JSON object with poll details: id, question, options, status,
+            result_mode, max_votes, votes, num_voters, voted_self.
+        """
+        client = get_client()
+        data = await client.ocs_get(f"apps/spreed/api/v1/poll/{token}/{poll_id}")
+        return json.dumps(_format_poll(data), indent=2, default=str)
+
+
+def _register_poll_tools(mcp: FastMCP) -> None:
+    """Register poll-related Talk tools (write + destructive)."""
+
+    @mcp.tool()
+    @require_permission(PermissionLevel.WRITE)
+    async def create_poll(
+        token: str,
+        question: str,
+        options: list[str],
+        result_mode: int = 0,
+        max_votes: int = 0,
+    ) -> str:
+        """Create a poll in a Talk conversation.
+
+        Polls can only be created in group or public conversations (not one-to-one).
+        A chat message is automatically posted announcing the poll.
+
+        Args:
+            token: The conversation token. Use list_conversations to find tokens.
+            question: The poll question (max 32,000 characters).
+            options: List of voting options (minimum 2 options required).
+                     Example: ["Yes", "No", "Maybe"]
+            result_mode: 0 for public results (voters see results immediately after voting),
+                         1 for hidden results (results shown only after poll is closed).
+                         Default: 0 (public).
+            max_votes: Maximum number of options a user can vote for.
+                       0 means unlimited (user can select all options). Default: 0.
+
+        Returns:
+            JSON object with poll details: id, question, options, status, result_mode, max_votes.
+        """
+        if len(options) < 2:
+            raise ValueError("A poll requires at least 2 options.")
+        client = get_client()
+        post_data: dict[str, Any] = {
+            "question": question,
+            "options[]": options,
+            "resultMode": result_mode,
+            "maxVotes": max_votes,
+        }
+        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()
+    @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.
+
+        Voting replaces any previous vote — calling this again with different
+        option_ids changes your vote. You cannot vote on closed polls.
+
+        Args:
+            token: The conversation token.
+            poll_id: The poll ID. Use get_poll to see available polls.
+            option_ids: List of option indices to vote for (0-based).
+                        For example, if options are ["Yes", "No", "Maybe"],
+                        use [0] to vote "Yes", or [0, 2] to vote "Yes" and "Maybe".
+                        The number of choices must not exceed the poll's max_votes
+                        (0 means unlimited).
+
+        Returns:
+            JSON object with updated poll details including your votes (voted_self)
+            and current vote counts (if visible).
+        """
+        if not option_ids:
+            raise ValueError("You must vote for at least one option.")
+        client = get_client()
+        post_data: dict[str, Any] = {"optionIds[]": option_ids}
+        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()
+    @require_permission(PermissionLevel.DESTRUCTIVE)
+    async def close_poll(token: str, poll_id: int) -> str:
+        """Close a poll in a Talk conversation.
+
+        Once closed, no more votes can be cast and results become visible
+        to all participants (regardless of result_mode). Only the poll
+        creator or a conversation moderator can close a poll.
+
+        This action is irreversible — a closed poll cannot be reopened.
+
+        Args:
+            token: The conversation token.
+            poll_id: The poll ID to close.
+
+        Returns:
+            JSON object with the final poll results including all votes and details.
+        """
+        client = get_client()
+        data = await client.ocs_delete(f"apps/spreed/api/v1/poll/{token}/{poll_id}")
+        return json.dumps(_format_poll(data), indent=2, default=str)
+
 
 def _register_write_tools(mcp: FastMCP) -> None:
-    """Register write and destructive Talk tools."""
+    """Register write and destructive Talk tools for conversations and messages."""
 
     @mcp.tool()
     @require_permission(PermissionLevel.WRITE)
@@ -299,4 +453,5 @@ async def leave_conversation(token: str) -> str:
 def register(mcp: FastMCP) -> None:
     """Register Talk tools with the MCP server."""
     _register_read_tools(mcp)
+    _register_poll_tools(mcp)
     _register_write_tools(mcp)

tests/integration/test_server.py

@@ -9,8 +9,10 @@
 pytestmark = pytest.mark.integration
 
 EXPECTED_TOOLS = [
+    "close_poll",
     "create_conversation",
     "create_directory",
+    "create_poll",
     "delete_file",
     "delete_message",
     "dismiss_all_notifications",
@@ -20,6 +22,7 @@
     "get_file",
     "get_messages",
     "get_participants",
+    "get_poll",
     "get_user",
     "leave_conversation",
     "list_conversations",
@@ -29,6 +32,7 @@
     "move_file",
     "send_message",
     "upload_file",
+    "vote_poll",
 ]