fix(client): resolve DAV paths via current-user-principal discovery

[dismantl]

I use external LDAP authentication for my Nextcloud instance, and nextcloud-mcp-server wouldn't work for my user account because its loginName and UID differ. This PR fixes that, and I deployed it to my Nextcloud 34 instance and it successfully solved the problem for me.

Problem

nextcloud-mcp-server builds every DAV path from the configured username, assuming that segment equals the user's canonical Nextcloud UID:

• WebDAV: /remote.php/dav/files/<username>/
• CardDAV: /remote.php/dav/addressbooks/users/<username>/
• CalDAV: /remote.php/dav/calendars/<username>/

That assumption holds on simple/local installs where loginName == UID, but breaks on LDAP and external-OIDC deployments where they can diverge. For example:

• Login Flow v2 returns loginName = alice
• OCS /cloud/user reports id = alice_1234 (LDAP-suffixed canonical UID)
• App-password BasicAuth succeeds, authenticating as alice
• DAV paths are built from alice, missing the real data at /files/alice_1234/

If a separate local user named alice exists, PROPFIND /files/alice/ can return 207 with empty or stale content. That creates silent wrong-path behavior rather than a clean 404. All three DAV clients are affected: WebDAV files, CardDAV contacts, and CalDAV calendars/tasks.

Fix

WebDAV + CardDAV (BaseNextcloudClient)

Add _ensure_principal_id() to client/base.py: a lazy PROPFIND /remote.php/dav/ requesting <d:current-user-principal/> (RFC 5397). On success, the last href segment is unquote()-decoded and cached as _principal_id. On failure (transport error, parse error, missing/empty href), a warning is logged and the method returns without caching, so the next call can retry.

_get_webdav_base_path() and _get_carddav_base_path() now call _principal_or_username() (discovered id or self.username fallback). Public DAV methods in webdav.py and contacts.py call await self._ensure_principal_id() before building paths.

CalDAV (CalendarClient)

CalendarClient uses the caldav library rather than raw PROPFIND. A new _ensure_calendar_home() method discovers the calendar home via principal().get_property(CalendarHomeSet) (RFC 4791, preferred), falls back to the calendar_home_set attribute, and falls back further to deriving the principal id from the principal URL. The result is cached in _calendar_home_url. Calendar and task methods that construct URLs guard with await self._ensure_calendar_home().

Safety net

The existing self.username remains the fallback at every step. When UID == loginName, discovery returns the same segment and paths are unchanged. If discovery is unavailable, existing username-based behavior is preserved.

Tests

The divergent-principal case cannot be reached in the integration suite because local Nextcloud users always have matching UID and loginName. New mocked unit tests in tests/unit/client/test_dav_principal_discovery.py cover:

• WebDAV / CardDAV divergent principal: discovery succeeds -> paths use discovered UID, not configured username
• Equal principal regression guard: UID == username -> paths unchanged
• Discovery failure -> fallback: transport error -> self.username path, no exception raised
• No-href / empty-href response: warning logged, no caching, fallback, retry on next call
• Caching: _ensure_principal_id() issues at most one PROPFIND per client instance
• URL decoding: percent-encoded principal hrefs (for example alice%40example.com) are decoded correctly
• CalDAV home-set preference: CalendarHomeSet discovery is preferred over deriving from the principal URL
• CalDAV async-safe lookup: get_property(CalendarHomeSet) is awaited correctly whether the caldav version returns a coroutine or a plain value
• CalDAV create/delete/events: all use the discovered home URL
• CalDAV discovery retry: a failed discovery does not permanently cache the fallback; the next call retries

Existing path-helper unit tests that build clients and call public methods are updated to pre-seed _principal_discovered = True, preserving existing _make_request call-order assertions.

The integration suite serves as the regression guard for the equal-case local-user behavior.

Relationship to PR #638

PR #638 introduced the same principal-discovery idea but bundles additional independent changes: CardDAV server-side query/limit, RU->LAT transliteration, resilient vCard BDAY parsing, and OCS sharing path normalization. This PR extracts only the DAV path identity fix as a standalone, focused change.

It also corrects a bug present in #638's implementation: unquote() was not applied to the extracted principal id, producing wrong paths for UIDs containing percent-encoded characters, such as OIDC sub-claims with @ or +.

The other changes from #638 are out of scope here and can be proposed as separate PRs.

Out of scope

• CardDAV server-side query/limit, transliteration, vCard BDAY parsing, and OCS sharing normalization
• Login Flow identity-layer storage, such as persisting canonical UID separately from loginName in context.py or the app-password store

The discovery approach fixes the DAV-path issue at the client layer for all deployment modes without a schema migration.

Validation

• Pre-push review completed
• uv run ruff check
• uv run ruff format --check
• uv run ty check -- nextcloud_mcp_server
• uv run pytest tests/unit/ -q -> 1908 passed, 1 skipped, 2 warnings
• Integration lane (NC32 single-user) -> 257 passed, 20 skipped, 2201 deselected, 1 xfailed
• Integration lane (NC33 single-user) -> 257 passed, 20 skipped, 2201 deselected, 1 xfailed
• Integration lane (NC32 multi-user-basic) -> 9 passed, 1 skipped, 2479 deselected, 4 warnings

Known xfail: tests/integration/test_mail_greenmail.py::test_send_message_via_outbox, a Mail/GreenMail outbox environment limitation unrelated to DAV principal discovery.

[CLAassistant]

All committers have signed the CLA.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[cbcoutinho]

Thanks for your contribution! I was able to reproduce the issue in a separate PR, and then once that was merged rebased your work onto the latest master - your fix resolves the issue and is safe to merge. Regressions will be handled by the integration tests in the future.