Merge pull request #809 from cbcoutinho/feat/deck-webhook-presets

feat(webhooks): add Deck card sync preset with vector indexing

nextcloud_mcp_server/app.py

@@ -2511,6 +2511,29 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
         response = await call_next(request)
         return response
 
+    # Log the inbound User-Agent on management API and webhook receiver routes
+    # so we can tell which Astrolabe (or other PHP-side client) build is
+    # talking to the backend. Astrolabe sends ``Nextcloud-Astrolabe/<version>``.
+    _UA_LOGGED_PATH_PREFIXES = ("/api/v1/", "/webhooks/nextcloud")
+
+    @app.middleware("http")
+    async def log_client_user_agent(request, call_next):
+        path = request.url.path
+        if path.startswith(_UA_LOGGED_PATH_PREFIXES):
+            ua = request.headers.get("user-agent") or "(none)"
+            logger.info(
+                "%s %s from %s",
+                request.method,
+                path,
+                ua,
+                extra={
+                    "user_agent": ua,
+                    "http_method": request.method,
+                    "http_path": path,
+                },
+            )
+        return await call_next(request)
+
     # Add CORS middleware to allow browser-based clients like MCP Inspector
     app.add_middleware(
         CORSMiddleware,  # type: ignore[invalid-argument-type]

nextcloud_mcp_server/server/webhook_presets.py

@@ -43,11 +43,18 @@ TABLES_EVENT_ROW_DELETED = "OCA\\Tables\\Event\\RowDeletedEvent"
 # Forms webhook events (Nextcloud 30+)
 FORMS_EVENT_FORM_SUBMITTED = "OCA\\Forms\\Events\\FormSubmittedEvent"
 
-# NOTE: Deck and Contacts do NOT support webhooks
-# Their event classes do not implement IWebhookCompatibleEvent interface.
-# Alternative sync strategies:
-# - Deck: Use polling with ETag-based change detection
-# - Contacts: Use CardDAV sync-token mechanism for efficient syncing
+# Deck webhook events (require nextcloud/deck PR #7910, which adds
+# IWebhookCompatibleEvent to these event classes). BoardUpdatedEvent only
+# carries a board ID and is used as a fan-out signal; the polling scanner
+# reconciles affected cards.
+DECK_EVENT_CARD_CREATED = "OCA\\Deck\\Event\\CardCreatedEvent"
+DECK_EVENT_CARD_UPDATED = "OCA\\Deck\\Event\\CardUpdatedEvent"
+DECK_EVENT_CARD_DELETED = "OCA\\Deck\\Event\\CardDeletedEvent"
+DECK_EVENT_BOARD_UPDATED = "OCA\\Deck\\Event\\BoardUpdatedEvent"
+
+# NOTE: Contacts does NOT support webhooks — its event classes do not
+# implement IWebhookCompatibleEvent. Use CardDAV sync-token mechanism for
+# efficient syncing.
 
 
 WEBHOOK_PRESETS: Dict[str, WebhookPreset] = {
@@ -138,6 +145,29 @@ WEBHOOK_PRESETS: Dict[str, WebhookPreset] = {
             },
         ],
     },
+    "deck_sync": {
+        "name": "Deck Sync",
+        "description": "Real-time synchronization for Deck cards (create, update, delete) and board updates",
+        "app": "deck",
+        "events": [
+            {
+                "event": DECK_EVENT_CARD_CREATED,
+                "filter": {},
+            },
+            {
+                "event": DECK_EVENT_CARD_UPDATED,
+                "filter": {},
+            },
+            {
+                "event": DECK_EVENT_CARD_DELETED,
+                "filter": {},
+            },
+            {
+                "event": DECK_EVENT_BOARD_UPDATED,
+                "filter": {},
+            },
+        ],
+    },
 }
 
 

nextcloud_mcp_server/vector/webhook_parser.py

@@ -4,8 +4,9 @@ Maps Nextcloud webhook events to vector-sync DocumentTasks. The handler at
 ``/webhooks/nextcloud`` calls :func:`extract_document_task` and forwards any
 non-None result to the same processor send-stream the scanner uses.
 
-Currently scoped to file (note) events. Calendar / Tables events fall through
-to ``None`` for now; those parsers can be added in follow-up changes.
+Currently scoped to file (note) events and Deck card events. Calendar /
+Tables events fall through to ``None`` for now; those parsers can be added
+in follow-up changes.
 
 See ADR-010 for the design and ``webhook-testing-findings.md`` for real
 captured payloads.
@@ -22,6 +23,19 @@ _FILE_EVENT_CREATED = "OCP\\Files\\Events\\Node\\NodeCreatedEvent"
 _FILE_EVENT_WRITTEN = "OCP\\Files\\Events\\Node\\NodeWrittenEvent"
 _FILE_EVENT_BEFORE_DELETED = "OCP\\Files\\Events\\Node\\BeforeNodeDeletedEvent"
 
+_DECK_EVENT_CARD_CREATED = "OCA\\Deck\\Event\\CardCreatedEvent"
+_DECK_EVENT_CARD_UPDATED = "OCA\\Deck\\Event\\CardUpdatedEvent"
+_DECK_EVENT_CARD_DELETED = "OCA\\Deck\\Event\\CardDeletedEvent"
+_DECK_EVENT_BOARD_UPDATED = "OCA\\Deck\\Event\\BoardUpdatedEvent"
+
+_DECK_CARD_EVENTS = frozenset(
+    {
+        _DECK_EVENT_CARD_CREATED,
+        _DECK_EVENT_CARD_UPDATED,
+        _DECK_EVENT_CARD_DELETED,
+    }
+)
+
 # Matches paths inside any user's Notes folder ending in .md, e.g.
 # "/admin/files/Notes/Sub/Note.md" or "/alice/files/Notes/foo.md".
 _NOTES_PATH_RE = re.compile(r"^/[^/]+/files/Notes/.+\.md$")
@@ -50,6 +64,9 @@ def extract_document_task(payload: dict) -> DocumentTask | None:
     ):
         return _parse_file_event(event_class, event, user_id, time)
 
+    if event_class in _DECK_CARD_EVENTS or event_class == _DECK_EVENT_BOARD_UPDATED:
+        return _parse_deck_event(event_class, event, user_id, time)
+
     logger.debug("Ignoring webhook for unsupported event: %s", event_class)
     return None
 
@@ -85,3 +102,46 @@ def _parse_file_event(
         operation=operation,
         modified_at=time,
     )
+
+
+def _parse_deck_event(
+    event_class: str, event: dict, user_id: str, time: int
+) -> DocumentTask | None:
+    # BoardUpdatedEvent carries only ``boardId`` — there's no card identifier to
+    # index. Log delivery so we can confirm webhook arrival in the receiver
+    # logs, and let the polling scanner reconcile the affected cards.
+    if event_class == _DECK_EVENT_BOARD_UPDATED:
+        board_id = event.get("boardId")
+        logger.info(
+            "Deck board %s updated; polling scanner will reconcile cards",
+            board_id,
+        )
+        return None
+
+    card = event.get("card") or {}
+    card_id = card.get("id")
+    stack_id = card.get("stackId")
+
+    if card_id is None:
+        # Without an id we can't address Qdrant points; the polling scanner
+        # will pick the change up on its next pass.
+        logger.warning(
+            "Webhook %s missing card.id; falling back to scanner",
+            event_class,
+        )
+        return None
+
+    operation = "delete" if event_class == _DECK_EVENT_CARD_DELETED else "index"
+
+    # board_id is not part of the Card payload — processor.py falls back to
+    # iterating boards/stacks if it's missing, so we pass stack_id only.
+    metadata = {"stack_id": stack_id} if stack_id is not None else None
+
+    return DocumentTask(
+        user_id=user_id,
+        doc_id=str(card_id),
+        doc_type="deck_card",
+        operation=operation,
+        modified_at=time,
+        metadata=metadata,
+    )