Merge branch 'master' into feature/introduce_files_parsing_with_unstructured_service_for_webdav_files_retrieval

nextcloud_mcp_server/app.py

@@ -1,62 +1,370 @@
-import click
 import logging
-import uvicorn
+import os
 from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager, AsyncExitStack
+from contextlib import AsyncExitStack, asynccontextmanager
 from dataclasses import dataclass
 
+import click
+import httpx
+import uvicorn
+from mcp.server.auth.settings import AuthSettings
+from mcp.server.fastmcp import Context, FastMCP
+from pydantic import AnyHttpUrl
 from starlette.applications import Starlette
 from starlette.routing import Mount
 
-from mcp.server.fastmcp import Context, FastMCP
-
-from nextcloud_mcp_server.config import setup_logging
+from nextcloud_mcp_server.auth import NextcloudTokenVerifier, load_or_register_client
 from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.config import LOGGING_CONFIG, setup_logging
+from nextcloud_mcp_server.context import get_client as get_nextcloud_client
 from nextcloud_mcp_server.server import (
     configure_calendar_tools,
     configure_contacts_tools,
+    configure_cookbook_tools,
+    configure_deck_tools,
     configure_notes_tools,
+    configure_sharing_tools,
     configure_tables_tools,
     configure_webdav_tools,
-    configure_deck_tools,
 )
 
-
 logger = logging.getLogger(__name__)
 
 
+def validate_pkce_support(discovery: dict, discovery_url: str) -> None:
+    """
+    Validate that the OIDC provider properly advertises PKCE support.
+
+    According to RFC 8414, if code_challenge_methods_supported is absent,
+    it means the authorization server does not support PKCE.
+
+    MCP clients require PKCE with S256 and will refuse to connect if this
+    field is missing or doesn't include S256.
+    """
+
+    code_challenge_methods = discovery.get("code_challenge_methods_supported")
+
+    if code_challenge_methods is None:
+        click.echo("=" * 80, err=True)
+        click.echo(
+            "ERROR: OIDC CONFIGURATION ERROR - Missing PKCE Support Advertisement",
+            err=True,
+        )
+        click.echo("=" * 80, err=True)
+        click.echo(f"Discovery URL: {discovery_url}", err=True)
+        click.echo("", err=True)
+        click.echo(
+            "The OIDC discovery document is missing 'code_challenge_methods_supported'.",
+            err=True,
+        )
+        click.echo(
+            "According to RFC 8414, this means the server does NOT support PKCE.",
+            err=True,
+        )
+        click.echo("", err=True)
+        click.echo("⚠️  MCP clients (like Claude Code) WILL REJECT this provider!")
+        click.echo("", err=True)
+        click.echo("How to fix:", err=True)
+        click.echo(
+            "  1. Ensure PKCE is enabled in Nextcloud OIDC app settings", err=True
+        )
+        click.echo(
+            "  2. Update the OIDC app to advertise PKCE support in discovery", err=True
+        )
+        click.echo("  3. See: RFC 8414 Section 2 (Authorization Server Metadata)")
+        click.echo("=" * 80, err=True)
+        click.echo("", err=True)
+        return
+
+    if "S256" not in code_challenge_methods:
+        click.echo("=" * 80, err=True)
+        click.echo(
+            "WARNING: OIDC CONFIGURATION WARNING - S256 Challenge Method Not Advertised",
+            err=True,
+        )
+        click.echo("=" * 80, err=True)
+        click.echo(f"Discovery URL: {discovery_url}", err=True)
+        click.echo(f"Advertised methods: {code_challenge_methods}", err=True)
+        click.echo("", err=True)
+        click.echo("MCP specification requires S256 code challenge method.", err=True)
+        click.echo("Some clients may reject this provider.", err=True)
+        click.echo("=" * 80, err=True)
+        click.echo("", err=True)
+        return
+
+    click.echo(f"✓ PKCE support validated: {code_challenge_methods}")
+
+
 @dataclass
 class AppContext:
+    """Application context for BasicAuth mode."""
+
     client: NextcloudClient
 
 
+@dataclass
+class OAuthAppContext:
+    """Application context for OAuth mode."""
+
+    nextcloud_host: str
+    token_verifier: NextcloudTokenVerifier
+
+
+def is_oauth_mode() -> bool:
+    """
+    Determine if OAuth mode should be used.
+
+    OAuth mode is enabled when:
+    - NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD are NOT set
+    - Or explicitly enabled via configuration
+
+    Returns:
+        True if OAuth mode, False if BasicAuth mode
+    """
+    username = os.getenv("NEXTCLOUD_USERNAME")
+    password = os.getenv("NEXTCLOUD_PASSWORD")
+
+    # If both username and password are set, use BasicAuth
+    if username and password:
+        logger.info(
+            "BasicAuth mode detected (NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD set)"
+        )
+        return False
+
+    logger.info("OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)")
+    return True
+
+
 @asynccontextmanager
-async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
-    """Manage application lifecycle with type-safe context"""
-    # Initialize on startup
-    logging.info("Creating Nextcloud client")
+async def app_lifespan_basic(server: FastMCP) -> AsyncIterator[AppContext]:
+    """
+    Manage application lifecycle for BasicAuth mode.
+
+    Creates a single Nextcloud client with basic authentication
+    that is shared across all requests.
+    """
+    logger.info("Starting MCP server in BasicAuth mode")
+    logger.info("Creating Nextcloud client with BasicAuth")
+
     client = NextcloudClient.from_env()
-    logging.info("Client initialization wait complete.")
+    logger.info("Client initialization complete")
+
     try:
         yield AppContext(client=client)
     finally:
-        # Cleanup on shutdown
+        logger.info("Shutting down BasicAuth mode")
         await client.close()
 
 
+@asynccontextmanager
+async def app_lifespan_oauth(server: FastMCP) -> AsyncIterator[OAuthAppContext]:
+    """
+    Manage application lifecycle for OAuth mode.
+
+    Initializes OAuth client registration and token verifier.
+    Does NOT create a Nextcloud client - clients are created per-request.
+    """
+    logger.info("Starting MCP server in OAuth mode")
+
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        raise ValueError("NEXTCLOUD_HOST environment variable is required")
+
+    nextcloud_host = nextcloud_host.rstrip("/")
+
+    # Get OAuth discovery endpoint
+    discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+
+    try:
+        # Fetch OIDC discovery
+        async with httpx.AsyncClient() as client:
+            response = await client.get(discovery_url)
+            response.raise_for_status()
+            discovery = response.json()
+
+        logger.info(f"OIDC discovery successful: {discovery_url}")
+
+        # Extract endpoints
+        userinfo_uri = discovery["userinfo_endpoint"]
+        registration_endpoint = discovery.get("registration_endpoint")
+
+        logger.info(f"Userinfo endpoint: {userinfo_uri}")
+
+        # Handle client registration
+        client_id = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID")
+        client_secret = os.getenv("NEXTCLOUD_OIDC_CLIENT_SECRET")
+        storage_path = os.getenv(
+            "NEXTCLOUD_OIDC_CLIENT_STORAGE", ".nextcloud_oauth_client.json"
+        )
+
+        if client_id and client_secret:
+            logger.info("Using pre-configured OAuth client credentials")
+        elif registration_endpoint:
+            logger.info("Dynamic client registration available")
+            mcp_server_url = os.getenv(
+                "NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000"
+            )
+            redirect_uris = [f"{mcp_server_url}/oauth/callback"]
+
+            # Load or register client
+            client_info = await load_or_register_client(
+                nextcloud_url=nextcloud_host,
+                registration_endpoint=registration_endpoint,
+                storage_path=storage_path,
+                client_name="Nextcloud MCP Server",
+                redirect_uris=redirect_uris,
+            )
+
+            logger.info(f"OAuth client ready: {client_info.client_id[:16]}...")
+        else:
+            raise ValueError(
+                "OAuth mode requires either:\n"
+                "1. NEXTCLOUD_OIDC_CLIENT_ID and NEXTCLOUD_OIDC_CLIENT_SECRET, OR\n"
+                "2. Dynamic client registration enabled on Nextcloud OIDC app"
+            )
+
+        # Create token verifier
+        token_verifier = NextcloudTokenVerifier(
+            nextcloud_host=nextcloud_host, userinfo_uri=userinfo_uri
+        )
+
+        logger.info("OAuth initialization complete")
+
+        try:
+            yield OAuthAppContext(
+                nextcloud_host=nextcloud_host, token_verifier=token_verifier
+            )
+        finally:
+            logger.info("Shutting down OAuth mode")
+            await token_verifier.close()
+
+    except Exception as e:
+        logger.error(f"Failed to initialize OAuth mode: {e}")
+        raise
+
+
+async def setup_oauth_config():
+    """
+    Setup OAuth configuration by performing OIDC discovery and client registration.
+
+    This is done synchronously before FastMCP initialization because FastMCP
+    requires token_verifier at construction time.
+
+    Returns:
+        Tuple of (nextcloud_host, token_verifier, auth_settings)
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        raise ValueError(
+            "NEXTCLOUD_HOST environment variable is required for OAuth mode"
+        )
+
+    nextcloud_host = nextcloud_host.rstrip("/")
+    discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+
+    logger.info(f"Performing OIDC discovery: {discovery_url}")
+
+    # Fetch OIDC discovery
+    async with httpx.AsyncClient() as client:
+        response = await client.get(discovery_url)
+        response.raise_for_status()
+        discovery = response.json()
+
+    logger.info("OIDC discovery successful")
+
+    # Validate PKCE support
+    validate_pkce_support(discovery, discovery_url)
+
+    # Extract endpoints
+    issuer = discovery["issuer"]
+    userinfo_uri = discovery["userinfo_endpoint"]
+    registration_endpoint = discovery.get("registration_endpoint")
+
+    # Allow override of public issuer URL for clients
+    # (useful when MCP server accesses Nextcloud via internal URL
+    # but needs to advertise a different URL to clients)
+    public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+    if public_issuer:
+        public_issuer = public_issuer.rstrip("/")
+        logger.info(f"Using public issuer URL for clients: {public_issuer}")
+        issuer = public_issuer
+
+    # Handle client registration
+    client_id = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID")
+    client_secret = os.getenv("NEXTCLOUD_OIDC_CLIENT_SECRET")
+
+    if client_id and client_secret:
+        logger.info("Using pre-configured OAuth client credentials")
+    elif registration_endpoint:
+        logger.info("Dynamic client registration available")
+        storage_path = os.getenv(
+            "NEXTCLOUD_OIDC_CLIENT_STORAGE", ".nextcloud_oauth_client.json"
+        )
+        mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
+        redirect_uris = [f"{mcp_server_url}/oauth/callback"]
+
+        # Load or register client
+        client_info = await load_or_register_client(
+            nextcloud_url=nextcloud_host,
+            registration_endpoint=registration_endpoint,
+            storage_path=storage_path,
+            client_name="Nextcloud MCP Server",
+            redirect_uris=redirect_uris,
+        )
+
+        logger.info(f"OAuth client ready: {client_info.client_id[:16]}...")
+    else:
+        raise ValueError(
+            "OAuth mode requires either:\n"
+            "1. NEXTCLOUD_OIDC_CLIENT_ID and NEXTCLOUD_OIDC_CLIENT_SECRET, OR\n"
+            "2. Dynamic client registration enabled on Nextcloud OIDC app"
+        )
+
+    # Create token verifier
+    token_verifier = NextcloudTokenVerifier(
+        nextcloud_host=nextcloud_host, userinfo_uri=userinfo_uri
+    )
+
+    # Create auth settings
+    mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
+    auth_settings = AuthSettings(
+        issuer_url=AnyHttpUrl(issuer),
+        resource_server_url=AnyHttpUrl(mcp_server_url),
+        required_scopes=["openid", "profile"],
+    )
+
+    logger.info("OAuth configuration complete")
+
+    return nextcloud_host, token_verifier, auth_settings
+
+
 def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     setup_logging()
 
-    # Create an MCP server
-    mcp = FastMCP("Nextcloud MCP", lifespan=app_lifespan)
+    # Determine authentication mode
+    oauth_enabled = is_oauth_mode()
+
+    if oauth_enabled:
+        logger.info("Configuring MCP server for OAuth mode")
+        # Asynchronously get the OAuth configuration
+        import asyncio
+
+        _, token_verifier, auth_settings = asyncio.run(setup_oauth_config())
+        mcp = FastMCP(
+            "Nextcloud MCP",
+            lifespan=app_lifespan_oauth,
+            token_verifier=token_verifier,
+            auth=auth_settings,
+        )
+    else:
+        logger.info("Configuring MCP server for BasicAuth mode")
+        mcp = FastMCP("Nextcloud MCP", lifespan=app_lifespan_basic)
 
     @mcp.resource("nc://capabilities")
     async def nc_get_capabilities():
         """Get the Nextcloud Host capabilities"""
-        ctx: Context = (
-            mcp.get_context()
-        )  # https://github.com/modelcontextprotocol/python-sdk/issues/244
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        ctx: Context = mcp.get_context()
+        client = get_nextcloud_client(ctx)
         return await client.capabilities()
 
     # Define available apps and their configuration functions
@@ -64,8 +372,10 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
         "notes": configure_notes_tools,
         "tables": configure_tables_tools,
         "webdav": configure_webdav_tools,
+        "sharing": configure_sharing_tools,
         "calendar": configure_calendar_tools,
         "contacts": configure_contacts_tools,
+        "cookbook": configure_cookbook_tools,
         "deck": configure_deck_tools,
     }
 
@@ -101,16 +411,19 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
 
 
 @click.command()
-@click.option("--host", "-h", default="127.0.0.1", show_default=True)
-@click.option("--port", "-p", type=int, default=8000, show_default=True)
-@click.option("--workers", "-w", type=int, default=None)
-@click.option("--reload", "-r", is_flag=True)
+@click.option(
+    "--host", "-h", default="127.0.0.1", show_default=True, help="Server host"
+)
+@click.option(
+    "--port", "-p", type=int, default=8000, show_default=True, help="Server port"
+)
 @click.option(
     "--log-level",
     "-l",
     default="info",
     show_default=True,
     type=click.Choice(["critical", "error", "warning", "info", "debug", "trace"]),
+    help="Logging level",
 )
 @click.option(
     "--transport",
@@ -118,40 +431,159 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     default="sse",
     show_default=True,
     type=click.Choice(["sse", "streamable-http", "http"]),
+    help="MCP transport protocol",
 )
 @click.option(
     "--enable-app",
     "-e",
     multiple=True,
-    type=click.Choice(["notes", "tables", "webdav", "calendar", "contacts", "deck"]),
+    type=click.Choice(
+        ["notes", "tables", "webdav", "calendar", "contacts", "cookbook", "deck"]
+    ),
     help="Enable specific Nextcloud app APIs. Can be specified multiple times. If not specified, all apps are enabled.",
 )
+@click.option(
+    "--oauth/--no-oauth",
+    default=None,
+    help="Force OAuth mode (if enabled) or BasicAuth mode (if disabled). By default, auto-detected based on environment variables.",
+)
+@click.option(
+    "--oauth-client-id",
+    envvar="NEXTCLOUD_OIDC_CLIENT_ID",
+    help="OAuth client ID (can also use NEXTCLOUD_OIDC_CLIENT_ID env var)",
+)
+@click.option(
+    "--oauth-client-secret",
+    envvar="NEXTCLOUD_OIDC_CLIENT_SECRET",
+    help="OAuth client secret (can also use NEXTCLOUD_OIDC_CLIENT_SECRET env var)",
+)
+@click.option(
+    "--oauth-storage-path",
+    envvar="NEXTCLOUD_OIDC_CLIENT_STORAGE",
+    default=".nextcloud_oauth_client.json",
+    show_default=True,
+    help="Path to store OAuth client credentials (can also use NEXTCLOUD_OIDC_CLIENT_STORAGE env var)",
+)
+@click.option(
+    "--mcp-server-url",
+    envvar="NEXTCLOUD_MCP_SERVER_URL",
+    default="http://localhost:8000",
+    show_default=True,
+    help="MCP server URL for OAuth callbacks (can also use NEXTCLOUD_MCP_SERVER_URL env var)",
+)
 def run(
     host: str,
     port: int,
-    workers: int,
-    reload: bool,
     log_level: str,
     transport: str,
     enable_app: tuple[str, ...],
+    oauth: bool | None,
+    oauth_client_id: str | None,
+    oauth_client_secret: str | None,
+    oauth_storage_path: str,
+    mcp_server_url: str,
 ):
+    """
+    Run the Nextcloud MCP server.
+
+    \b
+    Authentication Modes:
+      - BasicAuth: Set NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD
+      - OAuth: Leave USERNAME/PASSWORD unset (requires OIDC app enabled)
+
+    \b
+    Examples:
+      # BasicAuth mode (legacy)
+      $ nextcloud-mcp-server --host 0.0.0.0 --port 8000
+
+      # OAuth mode with auto-registration
+      $ nextcloud-mcp-server --oauth
+
+      # OAuth mode with pre-configured client
+      $ nextcloud-mcp-server --oauth --oauth-client-id=xxx --oauth-client-secret=yyy
+    """
+    # Set OAuth env vars from CLI options if provided
+    if oauth_client_id:
+        os.environ["NEXTCLOUD_OIDC_CLIENT_ID"] = oauth_client_id
+    if oauth_client_secret:
+        os.environ["NEXTCLOUD_OIDC_CLIENT_SECRET"] = oauth_client_secret
+    if oauth_storage_path:
+        os.environ["NEXTCLOUD_OIDC_CLIENT_STORAGE"] = oauth_storage_path
+    if mcp_server_url:
+        os.environ["NEXTCLOUD_MCP_SERVER_URL"] = mcp_server_url
+
+    # Force OAuth mode if explicitly requested
+    if oauth is True:
+        # Clear username/password to force OAuth mode
+        if "NEXTCLOUD_USERNAME" in os.environ:
+            click.echo(
+                "Warning: --oauth flag set, ignoring NEXTCLOUD_USERNAME", err=True
+            )
+            del os.environ["NEXTCLOUD_USERNAME"]
+        if "NEXTCLOUD_PASSWORD" in os.environ:
+            click.echo(
+                "Warning: --oauth flag set, ignoring NEXTCLOUD_PASSWORD", err=True
+            )
+            del os.environ["NEXTCLOUD_PASSWORD"]
+
+        # Validate OAuth configuration
+        nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+        if not nextcloud_host:
+            raise click.ClickException(
+                "OAuth mode requires NEXTCLOUD_HOST environment variable to be set"
+            )
+
+        # Check if we have client credentials OR if dynamic registration is possible
+        has_client_creds = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID") and os.getenv(
+            "NEXTCLOUD_OIDC_CLIENT_SECRET"
+        )
+
+        if not has_client_creds:
+            # No client credentials - will attempt dynamic registration
+            # Show helpful message before server starts
+            click.echo("", err=True)
+            click.echo("OAuth Configuration:", err=True)
+            click.echo("  Mode: Dynamic Client Registration", err=True)
+            click.echo("  Host: " + nextcloud_host, err=True)
+            click.echo(
+                "  Storage: "
+                + os.getenv(
+                    "NEXTCLOUD_OIDC_CLIENT_STORAGE", ".nextcloud_oauth_client.json"
+                ),
+                err=True,
+            )
+            click.echo("", err=True)
+            click.echo(
+                "Note: Make sure 'Dynamic Client Registration' is enabled", err=True
+            )
+            click.echo("      in your Nextcloud OIDC app settings.", err=True)
+            click.echo("", err=True)
+        else:
+            click.echo("", err=True)
+            click.echo("OAuth Configuration:", err=True)
+            click.echo("  Mode: Pre-configured Client", err=True)
+            click.echo("  Host: " + nextcloud_host, err=True)
+            click.echo(
+                "  Client ID: "
+                + os.getenv("NEXTCLOUD_OIDC_CLIENT_ID", "")[:16]
+                + "...",
+                err=True,
+            )
+            click.echo("", err=True)
+
+    elif oauth is False:
+        # Force BasicAuth mode - verify credentials exist
+        if not os.getenv("NEXTCLOUD_USERNAME") or not os.getenv("NEXTCLOUD_PASSWORD"):
+            raise click.ClickException(
+                "--no-oauth flag set but NEXTCLOUD_USERNAME or NEXTCLOUD_PASSWORD not set"
+            )
+
     enabled_apps = list(enable_app) if enable_app else None
 
-    if reload or workers:
-        app = "nextcloud_mcp_server.app:get_app"
-        factory = True
-    else:
-        app = get_app(transport=transport, enabled_apps=enabled_apps)
-        factory = False
+    app = get_app(transport=transport, enabled_apps=enabled_apps)
 
     uvicorn.run(
-        app=app,
-        factory=factory,
-        host=host,
-        port=port,
-        reload=reload,
-        workers=workers,
-        log_level=log_level,
+        app=app, host=host, port=port, log_level=log_level, log_config=LOGGING_CONFIG
     )
 
 

nextcloud_mcp_server/auth/__init__.py

@@ -0,0 +1,14 @@
+"""OAuth authentication components for Nextcloud MCP server."""
+
+from .bearer_auth import BearerAuth
+from .client_registration import load_or_register_client, register_client
+from .context_helper import get_client_from_context
+from .token_verifier import NextcloudTokenVerifier
+
+__all__ = [
+    "BearerAuth",
+    "NextcloudTokenVerifier",
+    "register_client",
+    "load_or_register_client",
+    "get_client_from_context",
+]

nextcloud_mcp_server/auth/bearer_auth.py

@@ -0,0 +1,34 @@
+"""Bearer token authentication for httpx."""
+
+from httpx import Auth, Request
+
+
+class BearerAuth(Auth):
+    """
+    Bearer token authentication flow for httpx.
+
+    This auth class adds the Authorization: Bearer <token> header
+    to all outgoing requests.
+    """
+
+    def __init__(self, token: str):
+        """
+        Initialize bearer authentication.
+
+        Args:
+            token: The bearer token to use for authentication
+        """
+        self.token = token
+
+    def auth_flow(self, request: Request):
+        """
+        Add Authorization header to the request.
+
+        Args:
+            request: The outgoing HTTP request
+
+        Yields:
+            The modified request with Authorization header
+        """
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        yield request

nextcloud_mcp_server/auth/client_registration.py

@@ -0,0 +1,261 @@
+"""Dynamic client registration for Nextcloud OIDC."""
+
+import datetime as dt
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class ClientInfo:
+    """Client registration information."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        client_id_issued_at: int,
+        client_secret_expires_at: int,
+        redirect_uris: list[str],
+    ):
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.client_id_issued_at = client_id_issued_at
+        self.client_secret_expires_at = client_secret_expires_at
+        self.redirect_uris = redirect_uris
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if the client has expired."""
+        return time.time() >= self.client_secret_expires_at
+
+    @property
+    def expires_soon(self) -> bool:
+        """Check if client expires within 5 minutes."""
+        return time.time() >= (self.client_secret_expires_at - 300)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for storage."""
+        return {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "client_id_issued_at": self.client_id_issued_at,
+            "client_secret_expires_at": self.client_secret_expires_at,
+            "redirect_uris": self.redirect_uris,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ClientInfo":
+        """Create from dictionary."""
+        return cls(
+            client_id=data["client_id"],
+            client_secret=data["client_secret"],
+            client_id_issued_at=data["client_id_issued_at"],
+            client_secret_expires_at=data["client_secret_expires_at"],
+            redirect_uris=data["redirect_uris"],
+        )
+
+
+async def register_client(
+    nextcloud_url: str,
+    registration_endpoint: str,
+    client_name: str = "Nextcloud MCP Server",
+    redirect_uris: list[str] | None = None,
+    scopes: str = "openid profile email",
+) -> ClientInfo:
+    """
+    Register a new OAuth client with Nextcloud OIDC using dynamic client registration.
+
+    Args:
+        nextcloud_url: Base URL of the Nextcloud instance
+        registration_endpoint: Full URL to the registration endpoint
+        client_name: Name of the client application
+        redirect_uris: List of redirect URIs (default: http://localhost:8000/oauth/callback)
+        scopes: Space-separated list of scopes to request
+
+    Returns:
+        ClientInfo with registration details
+
+    Raises:
+        httpx.HTTPStatusError: If registration fails
+        ValueError: If response is invalid
+    """
+    if redirect_uris is None:
+        redirect_uris = ["http://localhost:8000/oauth/callback"]
+
+    client_metadata = {
+        "client_name": client_name,
+        "redirect_uris": redirect_uris,
+        "token_endpoint_auth_method": "client_secret_post",
+        "grant_types": ["authorization_code", "refresh_token"],
+        "response_types": ["code"],
+        "scope": scopes,
+    }
+
+    logger.info(f"Registering OAuth client with Nextcloud: {client_name}")
+    logger.debug(f"Registration endpoint: {registration_endpoint}")
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            response = await client.post(
+                registration_endpoint,
+                json=client_metadata,
+                headers={"Content-Type": "application/json"},
+            )
+            response.raise_for_status()
+
+            client_info = response.json()
+            logger.info(
+                f"Successfully registered client: {client_info.get('client_id')}"
+            )
+            expires_at = dt.datetime.fromtimestamp(
+                client_info.get("client_secret_expires_at")
+            )
+            logger.info(
+                f"Client expires at: {expires_at} "
+                f"(in {client_info.get('client_secret_expires_at', 0) - int(time.time())} seconds)"
+            )
+
+            return ClientInfo(
+                client_id=client_info["client_id"],
+                client_secret=client_info["client_secret"],
+                client_id_issued_at=client_info.get(
+                    "client_id_issued_at", int(time.time())
+                ),
+                client_secret_expires_at=client_info.get(
+                    "client_secret_expires_at", int(time.time()) + 3600
+                ),
+                redirect_uris=client_info.get("redirect_uris", redirect_uris),
+            )
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Failed to register client: HTTP {e.response.status_code}")
+            logger.error(f"Response: {e.response.text}")
+            raise
+        except KeyError as e:
+            logger.error(f"Invalid response from registration endpoint: missing {e}")
+            raise ValueError(f"Invalid registration response: missing {e}")
+
+
+def load_client_from_file(storage_path: Path) -> ClientInfo | None:
+    """
+    Load client credentials from storage file.
+
+    Args:
+        storage_path: Path to the JSON file containing client credentials
+
+    Returns:
+        ClientInfo if file exists and is valid, None otherwise
+    """
+    if not storage_path.exists():
+        logger.debug(f"Client storage file not found: {storage_path}")
+        return None
+
+    try:
+        with open(storage_path, "r") as f:
+            data = json.load(f)
+
+        client_info = ClientInfo.from_dict(data)
+
+        if client_info.is_expired:
+            logger.warning(
+                f"Stored client has expired (expired at {client_info.client_secret_expires_at})"
+            )
+            return None
+
+        logger.info(f"Loaded client from storage: {client_info.client_id[:16]}...")
+        if client_info.expires_soon:
+            logger.warning("Client expires soon (within 5 minutes)")
+
+        return client_info
+
+    except (json.JSONDecodeError, KeyError, ValueError) as e:
+        logger.error(f"Failed to load client from file: {e}")
+        return None
+
+
+def save_client_to_file(client_info: ClientInfo, storage_path: Path):
+    """
+    Save client credentials to storage file.
+
+    Args:
+        client_info: Client information to save
+        storage_path: Path to save the JSON file
+
+    Raises:
+        OSError: If file cannot be written
+    """
+    try:
+        # Create directory if it doesn't exist
+        storage_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write client info
+        with open(storage_path, "w") as f:
+            json.dump(client_info.to_dict(), f, indent=2)
+
+        # Set restrictive permissions (owner read/write only)
+        os.chmod(storage_path, 0o600)
+
+        logger.info(f"Saved client credentials to {storage_path}")
+
+    except OSError as e:
+        logger.error(f"Failed to save client credentials: {e}")
+        raise
+
+
+async def load_or_register_client(
+    nextcloud_url: str,
+    registration_endpoint: str,
+    storage_path: str | Path,
+    client_name: str = "Nextcloud MCP Server",
+    redirect_uris: list[str] | None = None,
+) -> ClientInfo:
+    """
+    Load client from storage or register a new one if not found/expired.
+
+    This function:
+    1. Checks for existing client credentials in storage
+    2. Validates the credentials are not expired
+    3. Registers a new client if needed (no stored credentials or expired)
+    4. Saves the new client credentials
+
+    Args:
+        nextcloud_url: Base URL of the Nextcloud instance
+        registration_endpoint: Full URL to the registration endpoint
+        storage_path: Path to store client credentials
+        client_name: Name of the client application
+        redirect_uris: List of redirect URIs
+
+    Returns:
+        ClientInfo with valid credentials
+
+    Raises:
+        httpx.HTTPStatusError: If registration fails
+        ValueError: If response is invalid
+    """
+    storage_path = Path(storage_path)
+
+    # Try to load existing client
+    client_info = load_client_from_file(storage_path)
+    if client_info:
+        return client_info
+
+    # Register new client
+    logger.info("Registering new OAuth client...")
+    client_info = await register_client(
+        nextcloud_url=nextcloud_url,
+        registration_endpoint=registration_endpoint,
+        client_name=client_name,
+        redirect_uris=redirect_uris,
+    )
+
+    # Save to storage
+    save_client_to_file(client_info, storage_path)
+
+    return client_info

nextcloud_mcp_server/auth/context_helper.py

@@ -0,0 +1,65 @@
+"""Helper functions for extracting OAuth context from MCP requests."""
+
+import logging
+
+from mcp.server.auth.provider import AccessToken
+from mcp.server.fastmcp import Context
+
+from ..client import NextcloudClient
+
+logger = logging.getLogger(__name__)
+
+
+def get_client_from_context(ctx: Context, base_url: str) -> NextcloudClient:
+    """
+    Extract authenticated user context from MCP request and create NextcloudClient.
+
+    This function retrieves the OAuth access token from the MCP context,
+    extracts the username from the token's resource field (where we stored it
+    during token verification), and creates a NextcloudClient with bearer auth.
+
+    Args:
+        ctx: MCP request context containing session info
+        base_url: Nextcloud base URL
+
+    Returns:
+        NextcloudClient configured with bearer token auth
+
+    Raises:
+        AttributeError: If context doesn't contain expected OAuth session data
+        ValueError: If username cannot be extracted from token
+    """
+    try:
+        # In Starlette with FastMCP OAuth, the authenticated user info is stored in request.user
+        # The FastMCP auth middleware sets request.user to an AuthenticatedUser object
+        # which contains the access_token
+        if hasattr(ctx.request_context.request, "user") and hasattr(
+            ctx.request_context.request.user, "access_token"
+        ):
+            access_token: AccessToken = ctx.request_context.request.user.access_token
+            logger.debug("Retrieved access token from request.user for OAuth request")
+        else:
+            logger.error(
+                "OAuth authentication failed: No access token found in request"
+            )
+            raise AttributeError("No access token found in OAuth request context")
+
+        # Extract username from resource field (RFC 8707)
+        # We stored the username here during token verification
+        username = access_token.resource
+
+        if not username:
+            logger.error("No username found in access token resource field")
+            raise ValueError("Username not available in OAuth token context")
+
+        logger.debug(f"Creating OAuth NextcloudClient for user: {username}")
+
+        # Create client with bearer token
+        return NextcloudClient.from_token(
+            base_url=base_url, token=access_token.token, username=username
+        )
+
+    except AttributeError as e:
+        logger.error(f"Failed to extract OAuth context: {e}")
+        logger.error("This may indicate the server is not running in OAuth mode")
+        raise

nextcloud_mcp_server/auth/token_verifier.py

@@ -0,0 +1,207 @@
+"""Token verification using Nextcloud OIDC userinfo endpoint."""
+
+import logging
+import time
+from typing import Any
+
+import httpx
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+
+logger = logging.getLogger(__name__)
+
+
+class NextcloudTokenVerifier(TokenVerifier):
+    """
+    Validates access tokens using Nextcloud OIDC userinfo endpoint.
+
+    This verifier:
+    1. Calls the userinfo endpoint with the bearer token
+    2. Caches successful responses to avoid repeated API calls
+    3. Extracts username from the 'sub' or 'preferred_username' claim
+    4. Optionally supports JWT validation for performance (future enhancement)
+
+    The userinfo endpoint validates the token and returns user claims if valid,
+    or returns HTTP 400/401 if the token is invalid or expired.
+    """
+
+    def __init__(
+        self,
+        nextcloud_host: str,
+        userinfo_uri: str,
+        cache_ttl: int = 3600,
+    ):
+        """
+        Initialize the token verifier.
+
+        Args:
+            nextcloud_host: Base URL of the Nextcloud instance (e.g., https://cloud.example.com)
+            userinfo_uri: Full URL to the userinfo endpoint
+            cache_ttl: Time-to-live for cached tokens in seconds (default: 3600)
+        """
+        self.nextcloud_host = nextcloud_host.rstrip("/")
+        self.userinfo_uri = userinfo_uri
+        self.cache_ttl = cache_ttl
+
+        # Cache: token -> (userinfo, expiry_timestamp)
+        self._token_cache: dict[str, tuple[dict[str, Any], float]] = {}
+
+        # HTTP client for userinfo requests
+        self._client = httpx.AsyncClient(timeout=10.0)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """
+        Verify a bearer token by calling the userinfo endpoint.
+
+        This method:
+        1. Checks the cache first for recent validations
+        2. Calls the userinfo endpoint if not cached
+        3. Returns AccessToken with username stored in metadata
+
+        Args:
+            token: The bearer token to verify
+
+        Returns:
+            AccessToken if valid, None if invalid or expired
+        """
+        # Check cache first
+        cached = self._get_cached_token(token)
+        if cached:
+            logger.debug("Token found in cache")
+            return cached
+
+        # Validate via userinfo endpoint
+        try:
+            return await self._verify_via_userinfo(token)
+        except Exception as e:
+            logger.warning(f"Token verification failed: {e}")
+            return None
+
+    async def _verify_via_userinfo(self, token: str) -> AccessToken | None:
+        """
+        Validate token by calling the userinfo endpoint.
+
+        Args:
+            token: The bearer token to verify
+
+        Returns:
+            AccessToken if valid, None otherwise
+        """
+        try:
+            response = await self._client.get(
+                self.userinfo_uri, headers={"Authorization": f"Bearer {token}"}
+            )
+
+            if response.status_code == 200:
+                userinfo = response.json()
+                logger.debug(
+                    f"Token validated successfully for user: {userinfo.get('sub')}"
+                )
+
+                # Cache the result
+                expiry = time.time() + self.cache_ttl
+                self._token_cache[token] = (userinfo, expiry)
+
+                # Create AccessToken with username in resource field (workaround for MCP SDK)
+                username = userinfo.get("sub") or userinfo.get("preferred_username")
+                if not username:
+                    logger.error("No username found in userinfo response")
+                    return None
+
+                return AccessToken(
+                    token=token,
+                    client_id="",  # Not available from userinfo
+                    scopes=self._extract_scopes(userinfo),
+                    expires_at=int(expiry),
+                    resource=username,  # Store username in resource field (RFC 8707)
+                )
+
+            elif response.status_code in (400, 401, 403):
+                logger.info(f"Token validation failed: HTTP {response.status_code}")
+                return None
+            else:
+                logger.warning(
+                    f"Unexpected response from userinfo: {response.status_code}"
+                )
+                return None
+
+        except httpx.TimeoutException:
+            logger.error("Timeout while validating token via userinfo endpoint")
+            return None
+        except httpx.RequestError as e:
+            logger.error(f"Network error while validating token: {e}")
+            return None
+        except Exception as e:
+            logger.error(f"Unexpected error during token validation: {e}")
+            return None
+
+    def _get_cached_token(self, token: str) -> AccessToken | None:
+        """
+        Retrieve a token from cache if not expired.
+
+        Args:
+            token: The bearer token to look up
+
+        Returns:
+            AccessToken if cached and valid, None otherwise
+        """
+        if token not in self._token_cache:
+            return None
+
+        userinfo, expiry = self._token_cache[token]
+
+        # Check if expired
+        if time.time() >= expiry:
+            logger.debug("Cached token expired, removing from cache")
+            del self._token_cache[token]
+            return None
+
+        # Return cached AccessToken
+        username = userinfo.get("sub") or userinfo.get("preferred_username")
+        return AccessToken(
+            token=token,
+            client_id="",
+            scopes=self._extract_scopes(userinfo),
+            expires_at=int(expiry),
+            resource=username,
+        )
+
+    def _extract_scopes(self, userinfo: dict[str, Any]) -> list[str]:
+        """
+        Extract scopes from userinfo response.
+
+        Since the userinfo response doesn't include the original scopes,
+        we infer them from the claims present in the response.
+
+        Args:
+            userinfo: The userinfo response dictionary
+
+        Returns:
+            List of inferred scopes
+        """
+        scopes = ["openid"]  # Always present
+
+        if "email" in userinfo:
+            scopes.append("email")
+
+        if any(
+            key in userinfo for key in ["name", "given_name", "family_name", "picture"]
+        ):
+            scopes.append("profile")
+
+        if "roles" in userinfo:
+            scopes.append("roles")
+
+        if "groups" in userinfo:
+            scopes.append("groups")
+
+        return scopes
+
+    def clear_cache(self):
+        """Clear the token cache."""
+        self._token_cache.clear()
+        logger.debug("Token cache cleared")
+
+    async def close(self):
+        """Cleanup resources."""
+        await self._client.aclose()
+        logger.debug("Token verifier closed")

nextcloud_mcp_server/client/__init__.py

@@ -2,21 +2,25 @@ import logging
 import os
 
 from httpx import (
+    AsyncBaseTransport,
     AsyncClient,
+    AsyncHTTPTransport,
     Auth,
     BasicAuth,
     Request,
     Response,
-    AsyncBaseTransport,
-    AsyncHTTPTransport,
 )
 
 from ..controllers.notes_search import NotesSearchController
 from .calendar import CalendarClient
 from .contacts import ContactsClient
+from .cookbook import CookbookClient
 from .deck import DeckClient
+from .groups import GroupsClient
 from .notes import NotesClient
+from .sharing import SharingClient
 from .tables import TablesClient
+from .users import UsersClient
 from .webdav import WebDAVClient
 
 logger = logging.getLogger(__name__)
@@ -68,9 +72,15 @@ class NextcloudClient:
         self.notes = NotesClient(self._client, username)
         self.webdav = WebDAVClient(self._client, username)
         self.tables = TablesClient(self._client, username)
-        self.calendar = CalendarClient(self._client, username)
+        self.calendar = CalendarClient(
+            base_url, username, auth
+        )  # Uses AsyncDavClient internally
         self.contacts = ContactsClient(self._client, username)
+        self.cookbook = CookbookClient(self._client, username)
         self.deck = DeckClient(self._client, username)
+        self.users = UsersClient(self._client, username)
+        self.groups = GroupsClient(self._client, username)
+        self.sharing = SharingClient(self._client, username)
 
         # Initialize controllers
         self._notes_search = NotesSearchController()
@@ -85,6 +95,23 @@ class NextcloudClient:
         # Pass username to constructor
         return cls(base_url=host, username=username, auth=BasicAuth(username, password))
 
+    @classmethod
+    def from_token(cls, base_url: str, token: str, username: str):
+        """Create NextcloudClient with OAuth bearer token.
+
+        Args:
+            base_url: Nextcloud base URL
+            token: OAuth access token
+            username: Nextcloud username
+
+        Returns:
+            NextcloudClient configured with bearer token authentication
+        """
+        from ..auth import BearerAuth
+
+        logger.info(f"Creating NC Client for user '{username}' using OAuth token")
+        return cls(base_url=base_url, username=username, auth=BearerAuth(token))
+
     async def capabilities(self):
         response = await self._client.get(
             "/ocs/v2.php/cloud/capabilities",
@@ -96,13 +123,14 @@ class NextcloudClient:
 
     async def notes_search_notes(self, *, query: str):
         """Search notes using token-based matching with relevance ranking."""
-        all_notes = await self.notes.get_all_notes()
-        return self._notes_search.search_notes(all_notes, query)
+        all_notes = self.notes.get_all_notes()
+        return await self._notes_search.search_notes(all_notes, query)
 
     def _get_webdav_base_path(self) -> str:
         """Helper to get the base WebDAV path for the authenticated user."""
         return f"/remote.php/dav/files/{self.username}"
 
     async def close(self):
-        """Close the HTTP client."""
+        """Close the HTTP client and CalDAV client."""
         await self._client.aclose()
+        await self.calendar.close()

nextcloud_mcp_server/client/base.py

@@ -1,11 +1,11 @@
 """Base client for Nextcloud operations with shared authentication."""
 
 import logging
-from abc import ABC
-
-from functools import wraps
 import time
-from httpx import HTTPStatusError, codes, RequestError, AsyncClient
+from abc import ABC
+from functools import wraps
+
+from httpx import AsyncClient, HTTPStatusError, RequestError, codes
 
 logger = logging.getLogger(__name__)
 

nextcloud_mcp_server/client/contacts.py

@@ -1,10 +1,12 @@
 """CardDAV client for NextCloud contacts operations."""
 
 import logging
-from .base import BaseNextcloudClient
 import xml.etree.ElementTree as ET
+
 from pythonvCard4.vcard import Contact
 
+from .base import BaseNextcloudClient
+
 logger = logging.getLogger(__name__)
 
 

nextcloud_mcp_server/client/cookbook.py

@@ -0,0 +1,250 @@
+"""Client for Nextcloud Cookbook app operations."""
+
+import logging
+from typing import Any, Dict, List
+
+from httpx import Timeout
+
+from .base import BaseNextcloudClient
+
+logger = logging.getLogger(__name__)
+
+
+class CookbookClient(BaseNextcloudClient):
+    """Client for Nextcloud Cookbook app operations."""
+
+    async def get_version(self) -> Dict[str, Any]:
+        """Get Cookbook app and API version."""
+        response = await self._make_request("GET", "/apps/cookbook/api/version")
+        return response.json()
+
+    async def get_config(self) -> Dict[str, Any]:
+        """Get current Cookbook app configuration."""
+        response = await self._make_request("GET", "/apps/cookbook/api/v1/config")
+        return response.json()
+
+    async def set_config(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """Set Cookbook app configuration.
+
+        Args:
+            config: Configuration dictionary with fields like:
+                - folder: Recipe folder path
+                - update_interval: Auto-rescan interval in minutes
+                - print_image: Whether to print images with recipes
+                - visibleInfoBlocks: Visible info blocks configuration
+
+        Returns:
+            Response with status message
+        """
+        response = await self._make_request(
+            "POST", "/apps/cookbook/api/v1/config", json=config
+        )
+        return response.json()
+
+    async def reindex(self) -> str:
+        """Trigger a rescan of all recipes into the caching database.
+
+        Returns:
+            Success message
+        """
+        response = await self._make_request("POST", "/apps/cookbook/api/v1/reindex")
+        return response.json()
+
+    async def list_recipes(self) -> List[Dict[str, Any]]:
+        """Get all recipes in the database.
+
+        Returns:
+            List of recipe stubs with basic information
+        """
+        response = await self._make_request("GET", "/apps/cookbook/api/v1/recipes")
+        return response.json()
+
+    async def get_recipe(self, recipe_id: int) -> Dict[str, Any]:
+        """Get a single recipe by ID.
+
+        Args:
+            recipe_id: The recipe ID
+
+        Returns:
+            Full recipe data
+        """
+        response = await self._make_request(
+            "GET", f"/apps/cookbook/api/v1/recipes/{recipe_id}"
+        )
+        return response.json()
+
+    async def create_recipe(self, recipe_data: Dict[str, Any]) -> int:
+        """Create a new recipe.
+
+        Args:
+            recipe_data: Recipe data following schema.org/Recipe format.
+                Required: name
+                Optional: description, ingredients, instructions, etc.
+
+        Returns:
+            ID of the newly created recipe
+        """
+        response = await self._make_request(
+            "POST", "/apps/cookbook/api/v1/recipes", json=recipe_data
+        )
+        return response.json()
+
+    async def update_recipe(self, recipe_id: int, recipe_data: Dict[str, Any]) -> int:
+        """Update an existing recipe.
+
+        Args:
+            recipe_id: The recipe ID to update
+            recipe_data: Updated recipe data
+
+        Returns:
+            ID of the updated recipe
+        """
+        response = await self._make_request(
+            "PUT", f"/apps/cookbook/api/v1/recipes/{recipe_id}", json=recipe_data
+        )
+        return response.json()
+
+    async def delete_recipe(self, recipe_id: int) -> str:
+        """Delete a recipe.
+
+        Args:
+            recipe_id: The recipe ID to delete
+
+        Returns:
+            Success message
+        """
+        response = await self._make_request(
+            "DELETE", f"/apps/cookbook/api/v1/recipes/{recipe_id}"
+        )
+        return response.json()
+
+    async def import_recipe(self, url: str) -> Dict[str, Any]:
+        """Import a recipe from a URL using schema.org metadata.
+
+        Args:
+            url: URL of the recipe to import
+
+        Returns:
+            Full imported recipe data
+        """
+        logger.info(f"Importing recipe from URL: {url}")
+        response = await self._make_request(
+            "POST",
+            "/apps/cookbook/api/v1/import",
+            json={"url": url},
+            timeout=Timeout(300.0),
+        )
+        return response.json()
+
+    async def get_recipe_image(self, recipe_id: int, size: str = "full") -> bytes:
+        """Get the main image of a recipe.
+
+        Args:
+            recipe_id: The recipe ID
+            size: Image size - "full", "thumb" (250px), or "thumb16" (16px)
+
+        Returns:
+            Image bytes
+        """
+        response = await self._make_request(
+            "GET",
+            f"/apps/cookbook/api/v1/recipes/{recipe_id}/image",
+            params={"size": size},
+        )
+        return response.content
+
+    async def search_recipes(self, query: str) -> List[Dict[str, Any]]:
+        """Search for recipes by keywords, tags, and categories.
+
+        Args:
+            query: Search string (URL-encoded, space/comma separated)
+
+        Returns:
+            List of matching recipe stubs
+        """
+        # URL encode the query
+        from urllib.parse import quote
+
+        encoded_query = quote(query)
+        response = await self._make_request(
+            "GET", f"/apps/cookbook/api/v1/search/{encoded_query}"
+        )
+        return response.json()
+
+    async def list_categories(self) -> List[Dict[str, Any]]:
+        """Get all known categories.
+
+        Note: A category name of '*' indicates recipes with no category.
+
+        Returns:
+            List of categories with recipe counts
+        """
+        response = await self._make_request("GET", "/apps/cookbook/api/v1/categories")
+        return response.json()
+
+    async def get_recipes_in_category(self, category: str) -> List[Dict[str, Any]]:
+        """Get all recipes in a specific category.
+
+        Args:
+            category: Category name (use "_" for recipes with no category)
+
+        Returns:
+            List of recipe stubs in the category
+        """
+        from urllib.parse import quote
+
+        encoded_category = quote(category)
+        response = await self._make_request(
+            "GET", f"/apps/cookbook/api/v1/category/{encoded_category}"
+        )
+        return response.json()
+
+    async def rename_category(self, old_name: str, new_name: str) -> str:
+        """Rename a category.
+
+        Args:
+            old_name: Current category name
+            new_name: New category name
+
+        Returns:
+            New category name
+        """
+        from urllib.parse import quote
+
+        encoded_old_name = quote(old_name)
+        response = await self._make_request(
+            "PUT",
+            f"/apps/cookbook/api/v1/category/{encoded_old_name}",
+            json={"name": new_name},
+        )
+        return response.json()
+
+    async def list_keywords(self) -> List[Dict[str, Any]]:
+        """Get all known keywords/tags.
+
+        Returns:
+            List of keywords with recipe counts
+        """
+        response = await self._make_request("GET", "/apps/cookbook/api/v1/keywords")
+        return response.json()
+
+    async def get_recipes_with_keywords(
+        self, keywords: List[str]
+    ) -> List[Dict[str, Any]]:
+        """Get all recipes associated with certain keywords.
+
+        Args:
+            keywords: List of keywords to filter by
+
+        Returns:
+            List of recipe stubs matching the keywords
+        """
+        from urllib.parse import quote
+
+        # Join keywords with commas
+        keywords_str = ",".join(keywords)
+        encoded_keywords = quote(keywords_str)
+        response = await self._make_request(
+            "GET", f"/apps/cookbook/api/v1/tags/{encoded_keywords}"
+        )
+        return response.json()

nextcloud_mcp_server/client/deck.py

@@ -1,16 +1,16 @@
-from typing import List, Optional, Dict, Any
+from typing import Any, Dict, List, Optional
 
 from nextcloud_mcp_server.client.base import BaseNextcloudClient
 from nextcloud_mcp_server.models.deck import (
-    DeckBoard,
-    DeckStack,
-    DeckCard,
-    DeckLabel,
     DeckACL,
     DeckAttachment,
+    DeckBoard,
+    DeckCard,
     DeckComment,
-    DeckSession,
     DeckConfig,
+    DeckLabel,
+    DeckSession,
+    DeckStack,
 )
 
 
@@ -99,7 +99,7 @@ class DeckClient(BaseNextcloudClient):
         permission_edit: bool,
         permission_share: bool,
         permission_manage: bool,
-    ) -> List[DeckACL]:
+    ) -> DeckACL:
         json_data = {
             "type": type,
             "participant": participant,
@@ -107,10 +107,14 @@ class DeckClient(BaseNextcloudClient):
             "permissionShare": permission_share,
             "permissionManage": permission_manage,
         }
+        headers = self._get_deck_headers()
         response = await self._make_request(
-            "POST", f"/apps/deck/api/v1.0/boards/{board_id}/acl", json=json_data
+            "POST",
+            f"/apps/deck/api/v1.0/boards/{board_id}/acl",
+            json=json_data,
+            headers=headers,
         )
-        return [DeckACL(**acl) for acl in response.json()]
+        return DeckACL(**response.json())
 
     async def update_acl_rule(
         self,
@@ -127,13 +131,20 @@ class DeckClient(BaseNextcloudClient):
             json_data["permissionShare"] = permission_share
         if permission_manage is not None:
             json_data["permissionManage"] = permission_manage
+        headers = self._get_deck_headers()
         await self._make_request(
-            "PUT", f"/apps/deck/api/v1.0/boards/{board_id}/acl/{acl_id}", json=json_data
+            "PUT",
+            f"/apps/deck/api/v1.0/boards/{board_id}/acl/{acl_id}",
+            json=json_data,
+            headers=headers,
         )
 
     async def delete_acl_rule(self, board_id: int, acl_id: int) -> None:
+        headers = self._get_deck_headers()
         await self._make_request(
-            "DELETE", f"/apps/deck/api/v1.0/boards/{board_id}/acl/{acl_id}"
+            "DELETE",
+            f"/apps/deck/api/v1.0/boards/{board_id}/acl/{acl_id}",
+            headers=headers,
         )
 
     async def clone_board(

nextcloud_mcp_server/client/groups.py

@@ -0,0 +1,151 @@
+"""Nextcloud Groups API client."""
+
+import logging
+from typing import List
+
+from .base import BaseNextcloudClient, retry_on_429
+
+logger = logging.getLogger(__name__)
+
+
+class GroupsClient(BaseNextcloudClient):
+    """Client for Nextcloud Groups API operations."""
+
+    @retry_on_429
+    async def search_groups(
+        self,
+        search: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> List[str]:
+        """
+        Search for groups on the Nextcloud server.
+
+        Args:
+            search: Optional search string to filter groups
+            limit: Optional limit for number of results
+            offset: Optional offset for pagination
+
+        Returns:
+            List of group IDs matching the search criteria
+        """
+        params = {}
+        if search is not None:
+            params["search"] = search
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        response = await self._client.get(
+            "/ocs/v2.php/cloud/groups",
+            params=params,
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        groups = data["ocs"]["data"].get("groups", [])
+        return groups
+
+    @retry_on_429
+    async def create_group(self, groupid: str) -> None:
+        """
+        Create a new group.
+
+        Args:
+            groupid: The group ID to create
+
+        Raises:
+            HTTPStatusError: If the request fails (e.g., group already exists)
+        """
+        response = await self._client.post(
+            "/ocs/v2.php/cloud/groups",
+            data={"groupid": groupid},
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        logger.info(f"Created group: {groupid}")
+
+    @retry_on_429
+    async def delete_group(self, groupid: str) -> None:
+        """
+        Delete a group.
+
+        Args:
+            groupid: The group ID to delete
+
+        Raises:
+            HTTPStatusError: If the request fails (e.g., group doesn't exist)
+        """
+        response = await self._client.delete(
+            f"/ocs/v2.php/cloud/groups/{groupid}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        logger.info(f"Deleted group: {groupid}")
+
+    @retry_on_429
+    async def get_group_members(self, groupid: str) -> List[str]:
+        """
+        Get members of a group.
+
+        Args:
+            groupid: The group ID
+
+        Returns:
+            List of usernames in the group
+        """
+        response = await self._client.get(
+            f"/ocs/v2.php/cloud/groups/{groupid}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        users = data["ocs"]["data"].get("users", [])
+        return users
+
+    @retry_on_429
+    async def get_group_subadmins(self, groupid: str) -> List[str]:
+        """
+        Get subadmins of a group.
+
+        Args:
+            groupid: The group ID
+
+        Returns:
+            List of usernames who are subadmins of the group
+        """
+        response = await self._client.get(
+            f"/ocs/v2.php/cloud/groups/{groupid}/subadmins",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        # The API returns data as a list or dict depending on results
+        subadmins_data = data["ocs"]["data"]
+        if isinstance(subadmins_data, list):
+            return subadmins_data
+        return []
+
+    @retry_on_429
+    async def update_group_displayname(self, groupid: str, displayname: str) -> None:
+        """
+        Update a group's display name.
+
+        Args:
+            groupid: The group ID
+            displayname: The new display name
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        response = await self._client.put(
+            f"/ocs/v2.php/cloud/groups/{groupid}",
+            data={"key": "displayname", "value": displayname},
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        logger.info(f"Updated group {groupid} displayname to: {displayname}")

nextcloud_mcp_server/client/notes.py

@@ -1,7 +1,7 @@
 """Client for Nextcloud Notes app operations."""
 
 import logging
-from typing import Any, Dict, List, Optional
+from typing import Any, AsyncIterator, Dict, Optional
 
 from .base import BaseNextcloudClient
 
@@ -16,24 +16,22 @@ class NotesClient(BaseNextcloudClient):
         response = await self._make_request("GET", "/apps/notes/api/v1/settings")
         return response.json()
 
-    async def get_all_notes(self) -> List[Dict[str, Any]]:
-        """Get all notes."""
-        notes = []
+    async def get_all_notes(self) -> AsyncIterator[Dict[str, Any]]:
+        """Get all notes, yielding them one at a time."""
         cursor = ""
 
         while True:
             response = await self._make_request(
                 "GET",
                 "/apps/notes/api/v1/notes",
-                params={"chunkSize": 50, "chunkCursor": cursor},
+                params={"chunkSize": 10, "chunkCursor": cursor},
             )
-            notes.extend(response.json())
+            for note in response.json():
+                yield note
             if "X-Notes-Chunk-Cursor" not in response.headers:
                 break
             cursor = response.headers["X-Notes-Chunk-Cursor"]
 
-        return notes
-
     async def get_note(self, note_id: int) -> Dict[str, Any]:
         """Get a specific note by ID."""
         response = await self._make_request(

nextcloud_mcp_server/client/sharing.py

@@ -0,0 +1,208 @@
+"""Nextcloud OCS Sharing API client for file/folder sharing operations."""
+
+import logging
+from typing import Any
+
+from .base import BaseNextcloudClient, retry_on_429
+
+logger = logging.getLogger(__name__)
+
+
+class SharingClient(BaseNextcloudClient):
+    """Client for Nextcloud OCS Sharing API operations."""
+
+    @retry_on_429
+    async def create_share(
+        self,
+        path: str,
+        share_with: str,
+        share_type: int = 0,
+        permissions: int = 1,
+    ) -> dict[str, Any]:
+        """Create a share for a file or folder.
+
+        Args:
+            path: Path to file/folder to share (relative to user's files)
+            share_with: Username (for user share) or group name (for group share)
+            share_type: Share type (0=user, 1=group, 3=public link)
+            permissions: Share permissions:
+                - 1 = read
+                - 2 = update
+                - 4 = create
+                - 8 = delete
+                - 16 = share
+                - 31 = all permissions
+                Common combinations: 1 (read-only), 3 (read+update), 15 (read+update+create+delete)
+
+        Returns:
+            Share data including share ID
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        response = await self._client.post(
+            "/ocs/v2.php/apps/files_sharing/api/v1/shares",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+            data={
+                "path": path,
+                "shareType": share_type,
+                "shareWith": share_with,
+                "permissions": permissions,
+            },
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        # OCS API v2 uses HTTP-style status codes (200 for success)
+        # OCS API v1 used custom codes (100 for success)
+        ocs_status = data["ocs"]["meta"]["statuscode"]
+        if ocs_status not in (100, 200):
+            ocs_message = data["ocs"]["meta"].get("message", "Unknown error")
+            raise RuntimeError(f"OCS API error (code {ocs_status}): {ocs_message}")
+
+        share_data = data["ocs"]["data"]
+
+        # Handle case where data might be an empty list on error
+        if not share_data or (isinstance(share_data, list) and len(share_data) == 0):
+            ocs_message = data["ocs"]["meta"].get("message", "Unknown error")
+            raise RuntimeError(
+                f"Share creation failed: {ocs_message} (status {ocs_status})"
+            )
+
+        logger.info(
+            f"Created share {share_data['id']}: {path} -> {share_with} "
+            f"(type={share_type}, permissions={permissions})"
+        )
+        return share_data
+
+    @retry_on_429
+    async def delete_share(self, share_id: int) -> None:
+        """Delete a share by its ID.
+
+        Args:
+            share_id: The share ID to delete
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        response = await self._client.delete(
+            f"/ocs/v2.php/apps/files_sharing/api/v1/shares/{share_id}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        if data["ocs"]["meta"]["statuscode"] not in (100, 200):
+            raise RuntimeError(
+                f"OCS API error: {data['ocs']['meta'].get('message', 'Unknown error')}"
+            )
+
+        logger.info(f"Deleted share {share_id}")
+
+    @retry_on_429
+    async def get_share(self, share_id: int) -> dict[str, Any]:
+        """Get information about a specific share.
+
+        Args:
+            share_id: The share ID
+
+        Returns:
+            Share data
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        response = await self._client.get(
+            f"/ocs/v2.php/apps/files_sharing/api/v1/shares/{share_id}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        if data["ocs"]["meta"]["statuscode"] not in (100, 200):
+            raise RuntimeError(
+                f"OCS API error: {data['ocs']['meta'].get('message', 'Unknown error')}"
+            )
+
+        share_data = data["ocs"]["data"]
+        # The API returns a list with a single share, extract the first element
+        if isinstance(share_data, list) and len(share_data) > 0:
+            return share_data[0]
+        return share_data
+
+    @retry_on_429
+    async def list_shares(
+        self, path: str | None = None, shared_with_me: bool = False
+    ) -> list[dict[str, Any]]:
+        """List shares.
+
+        Args:
+            path: Optional path to filter shares for a specific file/folder
+            shared_with_me: If True, list shares shared with the current user
+
+        Returns:
+            List of share data
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        params = {}
+        if path:
+            params["path"] = path
+        if shared_with_me:
+            params["shared_with_me"] = "true"
+
+        response = await self._client.get(
+            "/ocs/v2.php/apps/files_sharing/api/v1/shares",
+            params=params,
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        if data["ocs"]["meta"]["statuscode"] not in (100, 200):
+            raise RuntimeError(
+                f"OCS API error: {data['ocs']['meta'].get('message', 'Unknown error')}"
+            )
+
+        # Handle both single share and list of shares
+        shares_data = data["ocs"]["data"]
+        if isinstance(shares_data, dict):
+            return [shares_data]
+        return shares_data if shares_data else []
+
+    @retry_on_429
+    async def update_share(
+        self, share_id: int, permissions: int | None = None
+    ) -> dict[str, Any]:
+        """Update a share's permissions.
+
+        Args:
+            share_id: The share ID to update
+            permissions: New permissions value (see create_share for values)
+
+        Returns:
+            Updated share data
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        data = {}
+        if permissions is not None:
+            data["permissions"] = permissions
+
+        response = await self._client.put(
+            f"/ocs/v2.php/apps/files_sharing/api/v1/shares/{share_id}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+            data=data,
+        )
+        response.raise_for_status()
+        result = response.json()
+
+        if result["ocs"]["meta"]["statuscode"] not in (100, 200):
+            raise RuntimeError(
+                f"OCS API error: {result['ocs']['meta'].get('message', 'Unknown error')}"
+            )
+
+        logger.info(f"Updated share {share_id}")
+        return result["ocs"]["data"]

nextcloud_mcp_server/client/users.py

@@ -0,0 +1,223 @@
+from typing import Dict, List, Optional
+
+from nextcloud_mcp_server.client.base import BaseNextcloudClient
+from nextcloud_mcp_server.models.users import UserDetails
+
+
+class UsersClient(BaseNextcloudClient):
+    """Client for Nextcloud User API operations."""
+
+    def _get_user_headers(
+        self, additional_headers: Optional[Dict[str, str]] = None
+    ) -> Dict[str, str]:
+        """Get standard headers required for User API calls."""
+        headers = {"OCS-APIRequest": "true", "Accept": "application/json"}
+        if additional_headers:
+            headers.update(additional_headers)
+        return headers
+
+    async def create_user(
+        self,
+        userid: str,
+        password: Optional[str] = None,
+        display_name: Optional[str] = None,
+        email: Optional[str] = None,
+        groups: Optional[List[str]] = None,
+        subadmin_groups: Optional[List[str]] = None,
+        quota: Optional[str] = None,
+        language: Optional[str] = None,
+    ) -> None:
+        """
+        Create a new user on the Nextcloud server.
+        """
+        data = {"userid": userid}
+        if password is not None:
+            data["password"] = password
+        if display_name is not None:
+            data["displayName"] = display_name
+        if email is not None:
+            data["email"] = email
+        if groups is not None:
+            for i, group in enumerate(groups):
+                data[f"groups[{i}]"] = group
+        if subadmin_groups is not None:
+            for i, group in enumerate(subadmin_groups):
+                data[f"subadmin[{i}]"] = group
+        if quota is not None:
+            data["quota"] = quota
+        if language is not None:
+            data["language"] = language
+
+        headers = self._get_user_headers()
+        await self._make_request(
+            "POST", "/ocs/v2.php/cloud/users", data=data, headers=headers
+        )
+
+    async def search_users(
+        self,
+        search: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[str]:
+        """
+        Retrieves a list of users from the Nextcloud server.
+        """
+        params = {}
+        if search is not None:
+            params["search"] = search
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", "/ocs/v2.php/cloud/users", params=params, headers=headers
+        )
+        # The v2 API returns JSON with users as a direct list under data.users
+        data = response.json()["ocs"]["data"]
+        return data.get("users", [])
+
+    async def get_user_details(self, userid: str) -> UserDetails:
+        """
+        Retrieves information about a single user.
+        """
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", f"/ocs/v2.php/cloud/users/{userid}", headers=headers
+        )
+        return UserDetails(**response.json()["ocs"]["data"])
+
+    async def update_user_field(self, userid: str, key: str, value: str) -> None:
+        """
+        Edits attributes related to a user.
+        """
+        data = {"key": key, "value": value}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "PUT", f"/ocs/v2.php/cloud/users/{userid}", data=data, headers=headers
+        )
+
+    async def get_editable_user_fields(self) -> List[str]:
+        """
+        Gets the list of editable data fields for a user.
+        """
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", "/ocs/v2.php/cloud/user/fields", headers=headers
+        )
+        # The v2 API returns data as a direct list
+        data = response.json()["ocs"]["data"]
+        return data if isinstance(data, list) else []
+
+    async def disable_user(self, userid: str) -> None:
+        """
+        Disables a user on the Nextcloud server.
+        """
+        headers = self._get_user_headers()
+        await self._make_request(
+            "PUT", f"/ocs/v2.php/cloud/users/{userid}/disable", headers=headers
+        )
+
+    async def enable_user(self, userid: str) -> None:
+        """
+        Enables a user on the Nextcloud server.
+        """
+        headers = self._get_user_headers()
+        await self._make_request(
+            "PUT", f"/ocs/v2.php/cloud/users/{userid}/enable", headers=headers
+        )
+
+    async def delete_user(self, userid: str) -> None:
+        """
+        Deletes a user from the Nextcloud server.
+        """
+        headers = self._get_user_headers()
+        await self._make_request(
+            "DELETE", f"/ocs/v2.php/cloud/users/{userid}", headers=headers
+        )
+
+    async def get_user_groups(self, userid: str) -> List[str]:
+        """
+        Retrieves a list of groups the specified user is a member of.
+        """
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", f"/ocs/v2.php/cloud/users/{userid}/groups", headers=headers
+        )
+        # The v2 API returns groups as a direct list under data.groups
+        data = response.json()["ocs"]["data"]
+        return data.get("groups", [])
+
+    async def add_user_to_group(self, userid: str, groupid: str) -> None:
+        """
+        Adds the specified user to the specified group.
+        """
+        data = {"groupid": groupid}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "POST",
+            f"/ocs/v2.php/cloud/users/{userid}/groups",
+            data=data,
+            headers=headers,
+        )
+
+    async def remove_user_from_group(self, userid: str, groupid: str) -> None:
+        """
+        Removes the specified user from the specified group.
+        """
+        data = {"groupid": groupid}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "DELETE",
+            f"/ocs/v2.php/cloud/users/{userid}/groups",
+            data=data,
+            headers=headers,
+        )
+
+    async def promote_user_to_subadmin(self, userid: str, groupid: str) -> None:
+        """
+        Makes a user the subadmin of a group.
+        """
+        data = {"groupid": groupid}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "POST",
+            f"/ocs/v2.php/cloud/users/{userid}/subadmins",
+            data=data,
+            headers=headers,
+        )
+
+    async def demote_user_from_subadmin(self, userid: str, groupid: str) -> None:
+        """
+        Removes the subadmin rights for the user specified from the group specified.
+        """
+        data = {"groupid": groupid}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "DELETE",
+            f"/ocs/v2.php/cloud/users/{userid}/subadmins",
+            data=data,
+            headers=headers,
+        )
+
+    async def get_user_subadmin_groups(self, userid: str) -> List[str]:
+        """
+        Returns the groups in which the user is a subadmin.
+        """
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", f"/ocs/v2.php/cloud/users/{userid}/subadmins", headers=headers
+        )
+        # The v2 API returns data as a direct list
+        data = response.json()["ocs"]["data"]
+        return data if isinstance(data, list) else []
+
+    async def resend_welcome_email(self, userid: str) -> None:
+        """
+        Triggers the welcome email for this user again.
+        """
+        headers = self._get_user_headers()
+        await self._make_request(
+            "POST", f"/ocs/v2.php/cloud/users/{userid}/welcome", headers=headers
+        )

nextcloud_mcp_server/client/webdav.py

@@ -570,3 +570,379 @@ class WebDAVClient(BaseNextcloudClient):
                 f"Unexpected error copying resource from '{source_path}' to '{destination_path}': {e}"
             )
             raise e
+
+    async def search_files(
+        self,
+        scope: str = "",
+        where_conditions: Optional[str] = None,
+        properties: Optional[List[str]] = None,
+        order_by: Optional[List[Tuple[str, str]]] = None,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """Search for files using WebDAV SEARCH method (RFC 5323).
+
+        Args:
+            scope: Directory path to search in (empty string for user root)
+            where_conditions: XML string for where clause conditions
+            properties: List of property names to retrieve (defaults to basic set)
+            order_by: List of (property, direction) tuples for sorting, e.g. [("getlastmodified", "descending")]
+            limit: Maximum number of results to return
+
+        Returns:
+            List of file/directory dictionaries with requested properties
+        """
+        # Default properties if not specified
+        if properties is None:
+            properties = [
+                "displayname",
+                "getcontentlength",
+                "getcontenttype",
+                "getlastmodified",
+                "resourcetype",
+                "getetag",
+            ]
+
+        # Build the SEARCH request XML
+        search_body = self._build_search_xml(
+            scope=scope,
+            where_conditions=where_conditions,
+            properties=properties,
+            order_by=order_by,
+            limit=limit,
+        )
+
+        # The SEARCH endpoint is at the dav root
+        search_path = "/remote.php/dav/"
+
+        headers = {"Content-Type": "text/xml", "OCS-APIRequest": "true"}
+
+        logger.debug(f"Searching files in scope: {scope}")
+
+        try:
+            response = await self._make_request(
+                "SEARCH", search_path, content=search_body, headers=headers
+            )
+            response.raise_for_status()
+
+            # Parse the XML response
+            results = self._parse_search_response(response.content, scope)
+
+            logger.debug(f"Search returned {len(results)} results")
+            return results
+
+        except HTTPStatusError as e:
+            logger.error(f"HTTP error during search: {e}")
+            raise e
+        except Exception as e:
+            logger.error(f"Unexpected error during search: {e}")
+            raise e
+
+    def _build_search_xml(
+        self,
+        scope: str,
+        where_conditions: Optional[str],
+        properties: List[str],
+        order_by: Optional[List[Tuple[str, str]]],
+        limit: Optional[int],
+    ) -> str:
+        """Build the XML body for a SEARCH request."""
+        # Construct the scope path
+        username = self.username
+        scope_path = f"/files/{username}"
+        if scope:
+            scope_path = f"{scope_path}/{scope.lstrip('/')}"
+
+        # Build property list
+        prop_xml = "\n".join([self._property_to_xml(prop) for prop in properties])
+
+        # Build where clause
+        where_xml = where_conditions if where_conditions else ""
+
+        # Build order by clause
+        orderby_xml = ""
+        if order_by:
+            order_elements = []
+            for prop, direction in order_by:
+                prop_element = self._property_to_xml(prop)
+                dir_element = (
+                    "<d:ascending/>"
+                    if direction.lower() == "ascending"
+                    else "<d:descending/>"
+                )
+                order_elements.append(f"<d:order>{prop_element}{dir_element}</d:order>")
+            orderby_xml = "\n".join(order_elements)
+        else:
+            orderby_xml = ""
+
+        # Build limit clause
+        limit_xml = (
+            f"<d:limit><d:nresults>{limit}</d:nresults></d:limit>" if limit else ""
+        )
+
+        # Construct the full SEARCH XML
+        search_xml = f"""<?xml version="1.0" encoding="UTF-8"?>
+<d:searchrequest xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
+    <d:basicsearch>
+        <d:select>
+            <d:prop>
+                {prop_xml}
+            </d:prop>
+        </d:select>
+        <d:from>
+            <d:scope>
+                <d:href>{scope_path}</d:href>
+                <d:depth>infinity</d:depth>
+            </d:scope>
+        </d:from>
+        <d:where>
+            {where_xml}
+        </d:where>
+        <d:orderby>
+            {orderby_xml}
+        </d:orderby>
+        {limit_xml}
+    </d:basicsearch>
+</d:searchrequest>"""
+
+        return search_xml
+
+    def _property_to_xml(self, prop: str) -> str:
+        """Convert a property name to its XML element."""
+        # Handle properties with namespace prefixes
+        if prop.startswith("{"):
+            # Already a full namespace
+            namespace_end = prop.index("}")
+            namespace = prop[1:namespace_end]
+            local_name = prop[namespace_end + 1 :]
+
+            # Map namespace URIs to prefixes
+            ns_map = {
+                "DAV:": "d",
+                "http://owncloud.org/ns": "oc",
+                "http://nextcloud.org/ns": "nc",
+            }
+
+            prefix = ns_map.get(namespace, "d")
+            return f"<{prefix}:{local_name}/>"
+        else:
+            # Guess namespace based on common properties
+            if prop in [
+                "displayname",
+                "getcontentlength",
+                "getcontenttype",
+                "getlastmodified",
+                "resourcetype",
+                "getetag",
+                "quota-available-bytes",
+                "quota-used-bytes",
+            ]:
+                return f"<d:{prop}/>"
+            elif prop in [
+                "fileid",
+                "size",
+                "permissions",
+                "favorite",
+                "tags",
+                "owner-id",
+                "owner-display-name",
+                "share-types",
+                "checksums",
+                "comments-count",
+                "comments-unread",
+            ]:
+                return f"<oc:{prop}/>"
+            else:
+                # Assume nc namespace for newer properties
+                return f"<nc:{prop}/>"
+
+    def _parse_search_response(
+        self, xml_content: bytes, scope: str
+    ) -> List[Dict[str, Any]]:
+        """Parse the XML response from a SEARCH request."""
+        root = ET.fromstring(xml_content)
+        items = []
+
+        # Process each response element
+        responses = root.findall(".//{DAV:}response")
+
+        for response_elem in responses:
+            href = response_elem.find(".//{DAV:}href")
+            if href is None:
+                continue
+
+            # Extract file/directory path from href
+            href_text = href.text or ""
+            # Remove the /remote.php/dav/files/username/ prefix to get relative path
+            path_parts = href_text.split("/files/")
+            if len(path_parts) > 1:
+                # Get the path after username
+                path_after_user = "/".join(path_parts[1].split("/")[1:])
+                relative_path = path_after_user.rstrip("/")
+            else:
+                relative_path = href_text.rstrip("/").split("/")[-1]
+
+            # Get properties
+            propstat = response_elem.find(".//{DAV:}propstat")
+            if propstat is None:
+                continue
+
+            prop = propstat.find(".//{DAV:}prop")
+            if prop is None:
+                continue
+
+            # Build item dictionary
+            item = {"path": relative_path, "href": href_text}
+
+            # Extract all properties
+            for child in prop:
+                tag = child.tag
+                value = child.text
+
+                # Remove namespace from tag
+                if "}" in tag:
+                    tag = tag.split("}", 1)[1]
+
+                # Handle special properties
+                if tag == "resourcetype":
+                    item["is_directory"] = child.find(".//{DAV:}collection") is not None
+                elif tag == "getcontentlength":
+                    item["size"] = int(value) if value else 0
+                elif tag == "displayname":
+                    item["name"] = value
+                elif tag == "getcontenttype":
+                    item["content_type"] = value
+                elif tag == "getlastmodified":
+                    item["last_modified"] = value
+                elif tag == "getetag":
+                    item["etag"] = value.strip('"') if value else None
+                elif tag == "fileid":
+                    item["file_id"] = int(value) if value else None
+                elif tag == "favorite":
+                    item["is_favorite"] = value == "1"
+                elif tag == "permissions":
+                    item["permissions"] = value
+                elif tag == "size":
+                    # oc:size includes folder sizes
+                    item["total_size"] = int(value) if value else 0
+                else:
+                    # Store other properties as-is
+                    item[tag] = value
+
+            items.append(item)
+
+        return items
+
+    async def find_by_name(
+        self, pattern: str, scope: str = "", limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Find files by name pattern using LIKE matching.
+
+        Args:
+            pattern: Name pattern to search for (supports % wildcard)
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            List of matching files/directories
+
+        Examples:
+            # Find all .txt files
+            results = await find_by_name("%.txt")
+
+            # Find files starting with "report"
+            results = await find_by_name("report%")
+        """
+        where_conditions = f"""
+            <d:like>
+                <d:prop>
+                    <d:displayname/>
+                </d:prop>
+                <d:literal>{pattern}</d:literal>
+            </d:like>
+        """
+
+        return await self.search_files(
+            scope=scope, where_conditions=where_conditions, limit=limit
+        )
+
+    async def find_by_type(
+        self, mime_type: str, scope: str = "", limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Find files by MIME type.
+
+        Args:
+            mime_type: MIME type to search for (supports % wildcard, e.g., "image/%")
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            List of matching files
+
+        Examples:
+            # Find all images
+            results = await find_by_type("image/%")
+
+            # Find all PDFs
+            results = await find_by_type("application/pdf")
+        """
+        where_conditions = f"""
+            <d:like>
+                <d:prop>
+                    <d:getcontenttype/>
+                </d:prop>
+                <d:literal>{mime_type}</d:literal>
+            </d:like>
+        """
+
+        return await self.search_files(
+            scope=scope, where_conditions=where_conditions, limit=limit
+        )
+
+    async def list_favorites(
+        self, scope: str = "", limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """List all favorite files.
+
+        Args:
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            List of favorite files/directories
+
+        Examples:
+            # List all favorites
+            results = await list_favorites()
+
+            # List favorites in a specific folder
+            results = await list_favorites(scope="Documents")
+        """
+        # Use REPORT method for favorites as it's more efficient
+        # But we can also use SEARCH as fallback
+        where_conditions = """
+            <d:eq>
+                <d:prop>
+                    <oc:favorite/>
+                </d:prop>
+                <d:literal>1</d:literal>
+            </d:eq>
+        """
+
+        # Request favorite property
+        properties = [
+            "displayname",
+            "getcontentlength",
+            "getcontenttype",
+            "getlastmodified",
+            "resourcetype",
+            "getetag",
+            "fileid",
+            "favorite",
+        ]
+
+        return await self.search_files(
+            scope=scope,
+            where_conditions=where_conditions,
+            properties=properties,
+            limit=limit,
+        )

nextcloud_mcp_server/config.py

@@ -4,17 +4,18 @@ from typing import Optional
 
 LOGGING_CONFIG = {
     "version": 1,
+    "disable_existing_loggers": False,
     "handlers": {
         "default": {
             "class": "logging.StreamHandler",
             "formatter": "http",
-        }
+        },
     },
     "formatters": {
         "http": {
             "format": "%(levelname)s [%(asctime)s] %(name)s - %(message)s",
             "datefmt": "%Y-%m-%d %H:%M:%S",
-        }
+        },
     },
     "loggers": {
         "": {
@@ -31,6 +32,21 @@ LOGGING_CONFIG = {
             "level": "INFO",
             "propagate": False,  # Prevent propagation to root logger
         },
+        "uvicorn": {
+            "handlers": ["default"],
+            "level": "INFO",
+            "propagate": False,
+        },
+        "uvicorn.access": {
+            "handlers": ["default"],
+            "level": "INFO",
+            "propagate": False,
+        },
+        "uvicorn.error": {
+            "handlers": ["default"],
+            "level": "INFO",
+            "propagate": False,
+        },
     },
 }
 

nextcloud_mcp_server/context.py

@@ -0,0 +1,51 @@
+"""Helper functions for accessing context in MCP tools."""
+
+from mcp.server.fastmcp import Context
+
+from nextcloud_mcp_server.client import NextcloudClient
+
+
+def get_client(ctx: Context) -> NextcloudClient:
+    """
+    Get the appropriate Nextcloud client based on authentication mode.
+
+    In BasicAuth mode, returns the shared client from lifespan context.
+    In OAuth mode, creates a new client per-request using the OAuth context.
+
+    This function automatically detects the authentication mode by checking
+    the type of the lifespan context.
+
+    Args:
+        ctx: MCP request context
+
+    Returns:
+        NextcloudClient configured for the current authentication mode
+
+    Raises:
+        AttributeError: If context doesn't contain expected data
+
+    Example:
+        ```python
+        @mcp.tool()
+        async def my_tool(ctx: Context):
+            client = get_client(ctx)
+            return await client.capabilities()
+        ```
+    """
+    lifespan_ctx = ctx.request_context.lifespan_context
+
+    # Try BasicAuth mode first (has 'client' attribute)
+    if hasattr(lifespan_ctx, "client"):
+        return lifespan_ctx.client
+
+    # OAuth mode (has 'nextcloud_host' attribute)
+    if hasattr(lifespan_ctx, "nextcloud_host"):
+        from nextcloud_mcp_server.auth import get_client_from_context
+
+        return get_client_from_context(ctx, lifespan_ctx.nextcloud_host)
+
+    # Unknown context type
+    raise AttributeError(
+        f"Lifespan context does not have 'client' or 'nextcloud_host' attribute. "
+        f"Type: {type(lifespan_ctx)}"
+    )

nextcloud_mcp_server/controllers/notes_search.py

@@ -1,13 +1,13 @@
 """Controller for notes search functionality."""
 
-from typing import Any, Dict, List
+from typing import Any, AsyncIterable, Dict, List
 
 
 class NotesSearchController:
     """Handles notes search logic and scoring."""
 
-    def search_notes(
-        self, notes: List[Dict[str, Any]], query: str
+    async def search_notes(
+        self, notes: AsyncIterable[Dict[str, Any]], query: str
     ) -> List[Dict[str, Any]]:
         """
         Search notes using token-based matching with relevance ranking.
@@ -21,7 +21,7 @@ class NotesSearchController:
             return []
 
         # Process and score each note
-        for note in notes:
+        async for note in notes:
             title_tokens, content_tokens = self._process_note_content(note)
             score = self._calculate_score(query_tokens, title_tokens, content_tokens)
 

nextcloud_mcp_server/models/__init__.py

@@ -1,41 +1,25 @@
 """Pydantic models for structured MCP server responses."""
 
 # Base models
-from .base import (
-    BaseResponse,
-    IdResponse,
-    StatusResponse,
-)
-
-# Notes models
-from .notes import (
-    Note,
-    NoteSearchResult,
-    NotesSettings,
-    CreateNoteResponse,
-    UpdateNoteResponse,
-    DeleteNoteResponse,
-    AppendContentResponse,
-    SearchNotesResponse,
-)
+from .base import BaseResponse, IdResponse, StatusResponse
 
 # Calendar models
 from .calendar import (
+    AvailabilitySlot,
+    BulkOperationResponse,
+    BulkOperationResult,
     Calendar,
     CalendarEvent,
     CalendarEventSummary,
     CreateEventResponse,
-    UpdateEventResponse,
-    DeleteEventResponse,
-    ListEventsResponse,
-    ListCalendarsResponse,
-    AvailabilitySlot,
-    FindAvailabilityResponse,
-    BulkOperationResult,
-    BulkOperationResponse,
     CreateMeetingResponse,
-    UpcomingEventsResponse,
+    DeleteEventResponse,
+    FindAvailabilityResponse,
+    ListCalendarsResponse,
+    ListEventsResponse,
     ManageCalendarResponse,
+    UpcomingEventsResponse,
+    UpdateEventResponse,
 )
 
 # Contacts models
@@ -43,38 +27,53 @@ from .contacts import (
     AddressBook,
     Contact,
     ContactField,
+    CreateAddressBookResponse,
+    CreateContactResponse,
+    DeleteAddressBookResponse,
+    DeleteContactResponse,
     ListAddressBooksResponse,
     ListContactsResponse,
-    CreateContactResponse,
     UpdateContactResponse,
-    DeleteContactResponse,
-    CreateAddressBookResponse,
-    DeleteAddressBookResponse,
+)
+
+# Notes models
+from .notes import (
+    AppendContentResponse,
+    CreateNoteResponse,
+    DeleteNoteResponse,
+    Note,
+    NoteSearchResult,
+    NotesSettings,
+    SearchNotesResponse,
+    UpdateNoteResponse,
 )
 
 # Tables models
 from .tables import (
+    CreateRowResponse,
+    DeleteRowResponse,
+    GetSchemaResponse,
+    ListTablesResponse,
+    ReadTableResponse,
     Table,
     TableColumn,
     TableRow,
-    TableView,
     TableSchema,
-    ListTablesResponse,
-    GetSchemaResponse,
-    ReadTableResponse,
-    CreateRowResponse,
+    TableView,
     UpdateRowResponse,
-    DeleteRowResponse,
 )
 
 # WebDAV models
 from .webdav import (
-    FileInfo,
-    DirectoryListing,
-    ReadFileResponse,
-    WriteFileResponse,
+    CopyResourceResponse,
     CreateDirectoryResponse,
     DeleteResourceResponse,
+    DirectoryListing,
+    FileInfo,
+    MoveResourceResponse,
+    ReadFileResponse,
+    SearchFilesResponse,
+    WriteFileResponse,
 )
 
 __all__ = [
@@ -137,4 +136,7 @@ __all__ = [
     "WriteFileResponse",
     "CreateDirectoryResponse",
     "DeleteResourceResponse",
+    "MoveResourceResponse",
+    "CopyResourceResponse",
+    "SearchFilesResponse",
 ]

nextcloud_mcp_server/models/calendar.py

@@ -180,3 +180,71 @@ class ManageCalendarResponse(BaseResponse):
         None, description="List of calendars (for list action)"
     )
     message: str = Field(description="Success message")
+
+
+# ============= Todo/Task Models =============
+
+
+class Todo(BaseModel):
+    """Model for a CalDAV todo/task (VTODO)."""
+
+    uid: str = Field(description="Todo UID")
+    summary: str = Field(description="Todo summary/title")
+    description: str = Field(default="", description="Todo description")
+    status: str = Field(
+        default="NEEDS-ACTION",
+        description="Todo status: NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED",
+    )
+    priority: int = Field(
+        default=0, description="Todo priority (0=undefined, 1=highest, 9=lowest)"
+    )
+    percent_complete: int = Field(default=0, description="Percentage complete (0-100)")
+    due: Optional[str] = Field(None, description="Due date/time (ISO format)")
+    dtstart: Optional[str] = Field(None, description="Start date/time (ISO format)")
+    completed: Optional[str] = Field(
+        None, description="Completion timestamp (ISO format)"
+    )
+    categories: str = Field(default="", description="Comma-separated categories")
+    href: str = Field(default="", description="CalDAV href")
+    etag: str = Field(default="", description="ETag for versioning")
+    calendar_name: Optional[str] = Field(
+        None, description="Calendar containing this todo"
+    )
+    calendar_display_name: Optional[str] = Field(
+        None, description="Display name of calendar containing this todo"
+    )
+
+
+class ListTodosResponse(BaseResponse):
+    """Response model for listing todos."""
+
+    todos: List[Todo] = Field(description="List of todos/tasks")
+    calendar_name: Optional[str] = Field(
+        None, description="Calendar name (if filtered to one calendar)"
+    )
+    total_count: int = Field(description="Total number of todos found")
+
+
+class CreateTodoResponse(BaseResponse):
+    """Response model for todo creation."""
+
+    todo: Todo = Field(description="The created todo")
+    calendar_name: str = Field(
+        description="Name of the calendar the todo was created in"
+    )
+
+
+class UpdateTodoResponse(BaseResponse):
+    """Response model for todo updates."""
+
+    todo: Todo = Field(description="The updated todo")
+    calendar_name: str = Field(description="Name of the calendar the todo belongs to")
+
+
+class DeleteTodoResponse(StatusResponse):
+    """Response model for todo deletion."""
+
+    deleted_uid: str = Field(description="UID of the deleted todo")
+    calendar_name: str = Field(
+        description="Name of the calendar the todo was deleted from"
+    )

nextcloud_mcp_server/models/cookbook.py

@@ -0,0 +1,220 @@
+"""Pydantic models for Cookbook app responses."""
+
+from typing import List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from .base import BaseResponse, IdResponse, StatusResponse
+
+
+class Nutrition(BaseModel):
+    """Nutrition information following schema.org/NutritionInformation."""
+
+    type: str = Field(
+        default="NutritionInformation",
+        alias="@type",
+        description="Schema.org object type",
+    )
+    calories: Optional[str] = Field(None, description="Calories (e.g., '650 kcal')")
+    carbohydrateContent: Optional[str] = Field(
+        None, description="Carbohydrates (e.g., '300 g')"
+    )
+    cholesterolContent: Optional[str] = Field(
+        None, description="Cholesterol (e.g., '10 g')"
+    )
+    fatContent: Optional[str] = Field(None, description="Fat (e.g., '45 g')")
+    fiberContent: Optional[str] = Field(None, description="Fiber (e.g., '50 g')")
+    proteinContent: Optional[str] = Field(None, description="Protein (e.g., '80 g')")
+    saturatedFatContent: Optional[str] = Field(
+        None, description="Saturated fat (e.g., '5 g')"
+    )
+    servingSize: Optional[str] = Field(
+        None, description="Serving size description (e.g., 'One plate')"
+    )
+    sodiumContent: Optional[str] = Field(None, description="Sodium (e.g., '10 mg')")
+    sugarContent: Optional[str] = Field(None, description="Sugar (e.g., '5 g')")
+    transFatContent: Optional[str] = Field(None, description="Trans fat (e.g., '10 g')")
+    unsaturatedFatContent: Optional[str] = Field(
+        None, description="Unsaturated fat (e.g., '40 g')"
+    )
+
+    class Config:
+        populate_by_name = True
+
+
+class RecipeStub(BaseModel):
+    """Stub of a recipe with basic information."""
+
+    id: str = Field(description="Recipe ID as string")
+    recipe_id: int = Field(description="Recipe ID as integer (deprecated)")
+    name: str = Field(description="Recipe name")
+    keywords: Optional[str] = Field(default="", description="Comma-separated keywords")
+    dateCreated: str = Field(description="Creation date (ISO8601)")
+    dateModified: Optional[str] = Field(
+        None, description="Last modified date (ISO8601)"
+    )
+    imageUrl: str = Field(default="", description="URL of the recipe image")
+    imagePlaceholderUrl: str = Field(default="", description="URL of placeholder image")
+
+
+class Recipe(BaseModel):
+    """Full recipe following schema.org/Recipe specification."""
+
+    type: str = Field(default="Recipe", alias="@type", description="Schema.org type")
+    id: Optional[str] = Field(None, description="Recipe ID")
+    name: str = Field(description="Recipe name")
+    description: str = Field(default="", description="Recipe description")
+    url: str = Field(default="", description="Original recipe URL")
+    image: str = Field(default="", description="URL of original recipe image")
+    imageUrl: Optional[str] = Field(
+        None, description="URL of the recipe image in Nextcloud"
+    )
+    imagePlaceholderUrl: Optional[str] = Field(
+        None, description="URL of placeholder image"
+    )
+    keywords: str = Field(default="", description="Comma-separated keywords")
+    dateCreated: Optional[str] = Field(None, description="Creation date (ISO8601)")
+    dateModified: Optional[str] = Field(
+        None, description="Last modified date (ISO8601)"
+    )
+    prepTime: Optional[str] = Field(None, description="Preparation time (ISO8601)")
+    cookTime: Optional[str] = Field(None, description="Cooking time (ISO8601)")
+    totalTime: Optional[str] = Field(None, description="Total time (ISO8601)")
+    recipeYield: Union[int, str] = Field(default=1, description="Number of servings")
+    recipeCategory: str = Field(default="", description="Recipe category")
+    tool: List[str] = Field(default_factory=list, description="Required tools")
+    recipeIngredient: List[str] = Field(
+        default_factory=list, description="List of ingredients"
+    )
+    recipeInstructions: List[str] = Field(
+        default_factory=list, description="Cooking instructions"
+    )
+    nutrition: Optional[Nutrition] = Field(None, description="Nutrition information")
+
+    class Config:
+        populate_by_name = True
+        extra = "allow"  # Allow additional schema.org fields
+
+
+class Category(BaseModel):
+    """A recipe category."""
+
+    name: str = Field(description="Category name")
+    recipe_count: int = Field(description="Number of recipes in category")
+
+
+class Keyword(BaseModel):
+    """A recipe keyword/tag."""
+
+    name: str = Field(description="Keyword name")
+    recipe_count: int = Field(description="Number of recipes with this keyword")
+
+
+class VisibleInfoBlocks(BaseModel):
+    """Configuration for visible information blocks in the UI."""
+
+    preparation_time: Optional[bool] = Field(
+        None, alias="preparation-time", description="Show preparation time"
+    )
+    cooking_time: Optional[bool] = Field(
+        None, alias="cooking-time", description="Show cooking time"
+    )
+    total_time: Optional[bool] = Field(
+        None, alias="total-time", description="Show total time"
+    )
+    nutrition_information: Optional[bool] = Field(
+        None, alias="nutrition-information", description="Show nutrition info"
+    )
+    tools: Optional[bool] = Field(None, description="Show tools list")
+
+    class Config:
+        populate_by_name = True
+
+
+class CookbookConfig(BaseModel):
+    """Cookbook app configuration."""
+
+    folder: Optional[str] = Field(None, description="Recipe folder path")
+    update_interval: Optional[int] = Field(
+        None, description="Auto-rescan interval in minutes"
+    )
+    print_image: Optional[bool] = Field(None, description="Print images with recipes")
+    visibleInfoBlocks: Optional[VisibleInfoBlocks] = Field(
+        None, description="Visible info blocks configuration"
+    )
+
+
+class APIVersion(BaseModel):
+    """API version information."""
+
+    epoch: int = Field(description="API epoch")
+    major: int = Field(description="Major version")
+    minor: int = Field(description="Minor version")
+
+
+class Version(BaseModel):
+    """Version information for Cookbook app and API."""
+
+    cookbook_version: List[int] = Field(description="Cookbook app version")
+    api_version: APIVersion = Field(description="API version")
+
+
+# Response models for MCP tools
+
+
+class ImportRecipeResponse(BaseResponse):
+    """Response model for recipe import."""
+
+    recipe: Recipe = Field(description="The imported recipe")
+    recipe_id: str = Field(description="ID of the imported recipe")
+
+
+class CreateRecipeResponse(IdResponse):
+    """Response model for recipe creation."""
+
+    pass
+
+
+class UpdateRecipeResponse(IdResponse):
+    """Response model for recipe update."""
+
+    pass
+
+
+class DeleteRecipeResponse(StatusResponse):
+    """Response model for recipe deletion."""
+
+    deleted_id: int = Field(description="ID of deleted recipe")
+
+
+class ListRecipesResponse(BaseResponse):
+    """Response model for listing recipes."""
+
+    recipes: List[RecipeStub] = Field(description="List of recipe stubs")
+    total_count: int = Field(description="Total number of recipes")
+
+
+class SearchRecipesResponse(BaseResponse):
+    """Response model for recipe search."""
+
+    recipes: List[RecipeStub] = Field(description="Matching recipes")
+    query: str = Field(description="Search query used")
+    total_found: int = Field(description="Number of recipes found")
+
+
+class ListCategoriesResponse(BaseResponse):
+    """Response model for listing categories."""
+
+    categories: List[Category] = Field(description="List of categories")
+
+
+class ListKeywordsResponse(BaseResponse):
+    """Response model for listing keywords."""
+
+    keywords: List[Keyword] = Field(description="List of keywords")
+
+
+class ReindexResponse(StatusResponse):
+    """Response model for reindex operation."""
+
+    pass

nextcloud_mcp_server/models/deck.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from typing import List, Optional, Dict, Any, Union
+from typing import Any, Dict, List, Optional, Union
 
 from pydantic import BaseModel, Field, field_validator
 

nextcloud_mcp_server/models/users.py

@@ -0,0 +1,41 @@
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class User(BaseModel):
+    """Model for creating a new user."""
+
+    userid: str
+    password: Optional[str] = None
+    displayName: Optional[str] = None
+    email: Optional[str] = None
+    groups: Optional[List[str]] = Field(default_factory=list)
+    subadmin: Optional[List[str]] = Field(default_factory=list)
+    quota: Optional[str] = None
+    language: Optional[str] = None
+
+
+class UserDetails(BaseModel):
+    """Model for retrieving detailed user information."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    enabled: bool
+    id: str
+    quota: Union[str, Dict[str, Any]]  # Can be string or quota object
+    email: Optional[str] = None  # Can be null
+    displayname: str = Field(
+        alias="display-name"
+    )  # Handle both displayname and display-name
+    phone: Optional[str] = None
+    address: Optional[str] = None
+    website: Optional[str] = None
+    twitter: Optional[str] = None
+    groups: Optional[List[str]] = Field(default_factory=list)
+
+
+class Group(BaseModel):
+    """Model for a user group."""
+
+    id: str

nextcloud_mcp_server/models/webdav.py

@@ -22,6 +22,8 @@ class FileInfo(BaseModel):
         None, description="Last modification time (ISO format)"
     )
     etag: Optional[str] = Field(None, description="ETag for versioning")
+    file_id: Optional[int] = Field(None, description="Nextcloud file ID")
+    is_favorite: Optional[bool] = Field(None, description="Whether file is favorited")
 
     @property
     def last_modified_datetime(self) -> Optional[datetime]:
@@ -106,3 +108,14 @@ class CopyResourceResponse(StatusResponse):
     overwrite: bool = Field(
         description="Whether the destination was overwritten if it existed"
     )
+
+
+class SearchFilesResponse(BaseResponse):
+    """Response model for WebDAV search operations."""
+
+    results: List[FileInfo] = Field(description="Search results")
+    total_found: int = Field(description="Total number of files found")
+    scope: str = Field(description="The scope/path that was searched")
+    filters_applied: Optional[dict] = Field(
+        None, description="Filters that were applied to the search"
+    )

nextcloud_mcp_server/server/__init__.py

@@ -1,15 +1,19 @@
 from .calendar import configure_calendar_tools
+from .contacts import configure_contacts_tools
+from .cookbook import configure_cookbook_tools
+from .deck import configure_deck_tools
 from .notes import configure_notes_tools
+from .sharing import configure_sharing_tools
 from .tables import configure_tables_tools
 from .webdav import configure_webdav_tools
-from .contacts import configure_contacts_tools
-from .deck import configure_deck_tools
 
 __all__ = [
     "configure_calendar_tools",
     "configure_contacts_tools",
+    "configure_cookbook_tools",
     "configure_deck_tools",
     "configure_notes_tools",
+    "configure_sharing_tools",
     "configure_tables_tools",
     "configure_webdav_tools",
 ]

nextcloud_mcp_server/server/calendar.py

@@ -4,10 +4,12 @@ from typing import Optional
 
 from mcp.server.fastmcp import Context, FastMCP
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models.calendar import (
     Calendar,
     ListCalendarsResponse,
+    ListTodosResponse,
+    Todo,
 )
 
 logger = logging.getLogger(__name__)
@@ -18,7 +20,7 @@ def configure_calendar_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_calendar_list_calendars(ctx: Context) -> ListCalendarsResponse:
         """List all available calendars for the user"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         calendars_data = await client.calendar.list_calendars()
 
         calendars = [Calendar(**cal_data) for cal_data in calendars_data]
@@ -74,7 +76,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Dict with event creation result
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         event_data = {
             "title": title,
@@ -133,7 +135,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             List of events matching the filters
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Convert YYYY-MM-DD format dates to datetime objects
         start_datetime = None
@@ -207,7 +209,7 @@ def configure_calendar_tools(mcp: FastMCP):
         ctx: Context,
     ):
         """Get detailed information about a specific event"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         event_data, etag = await client.calendar.get_event(calendar_name, event_uid)
         return event_data
 
@@ -240,7 +242,7 @@ def configure_calendar_tools(mcp: FastMCP):
         etag: str = "",
     ):
         """Update any aspect of an existing event"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Build update data with only non-None values
         event_data = {}
@@ -290,7 +292,7 @@ def configure_calendar_tools(mcp: FastMCP):
         ctx: Context,
     ):
         """Delete a calendar event"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.calendar.delete_event(calendar_name, event_uid)
 
     @mcp.tool()
@@ -332,7 +334,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Dict with meeting creation result
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Combine date and time for start_datetime
         start_datetime = f"{date}T{time}:00"
@@ -366,7 +368,7 @@ def configure_calendar_tools(mcp: FastMCP):
         limit: int = 10,
     ):
         """Get upcoming events in next N days"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         now = dt.datetime.now()
         end_datetime = now + dt.timedelta(days=days_ahead)
@@ -435,7 +437,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             List of available time slots with start/end times and duration
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Parse attendees
         attendee_list = []
@@ -536,7 +538,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Summary of operation results including counts and details
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         if operation not in ["update", "delete", "move"]:
             raise ValueError("Operation must be 'update', 'delete', or 'move'")
@@ -758,7 +760,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Result of the calendar management operation
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         if action == "list":
             return await client.calendar.list_calendars()
@@ -799,3 +801,209 @@ def configure_calendar_tools(mcp: FastMCP):
 
         else:
             raise ValueError("Action must be 'create', 'delete', 'update', or 'list'")
+
+    # ============= Todo/Task Tools =============
+
+    @mcp.tool()
+    async def nc_calendar_list_todos(
+        calendar_name: str,
+        ctx: Context,
+        status: Optional[str] = None,
+        min_priority: Optional[int] = None,
+        categories: Optional[str] = None,
+        summary_contains: Optional[str] = None,
+    ) -> ListTodosResponse:
+        """List todos/tasks in a calendar with optional filtering.
+
+        Args:
+            calendar_name: Name of the calendar to list todos from
+            ctx: MCP context
+            status: Filter by status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
+            min_priority: Filter by minimum priority (1=highest, 9=lowest)
+            categories: Filter by categories (comma-separated, e.g., "work,urgent")
+            summary_contains: Filter todos where summary contains this text
+
+        Returns:
+            List of todos matching the filters
+        """
+        client = get_client(ctx)
+
+        # Build filters dictionary
+        filters = {}
+        if status is not None:
+            filters["status"] = status
+        if min_priority is not None:
+            filters["min_priority"] = min_priority
+        if categories is not None:
+            filters["categories"] = [cat.strip() for cat in categories.split(",")]
+        if summary_contains is not None:
+            filters["summary_contains"] = summary_contains
+
+        todos_data = await client.calendar.list_todos(
+            calendar_name, filters if filters else None
+        )
+
+        todos = [Todo(**todo_data) for todo_data in todos_data]
+        return ListTodosResponse(
+            todos=todos, calendar_name=calendar_name, total_count=len(todos)
+        )
+
+    @mcp.tool()
+    async def nc_calendar_create_todo(
+        calendar_name: str,
+        summary: str,
+        ctx: Context,
+        description: str = "",
+        status: str = "NEEDS-ACTION",
+        priority: int = 0,
+        due: str = "",
+        dtstart: str = "",
+        categories: str = "",
+    ):
+        """Create a new todo/task in a calendar.
+
+        Args:
+            calendar_name: Name of the calendar to create the todo in
+            summary: Todo title/summary
+            ctx: MCP context
+            description: Detailed description of the todo
+            status: Todo status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
+            priority: Priority (0=undefined, 1=highest, 9=lowest)
+            due: Due date/time (ISO format, e.g., "2025-01-15T14:00:00")
+            dtstart: Start date/time (ISO format)
+            categories: Comma-separated categories (e.g., "work,urgent")
+
+        Returns:
+            Dict with todo creation result
+        """
+        client = get_client(ctx)
+
+        todo_data = {
+            "summary": summary,
+            "description": description,
+            "status": status,
+            "priority": priority,
+            "due": due,
+            "dtstart": dtstart,
+            "categories": categories,
+        }
+
+        return await client.calendar.create_todo(calendar_name, todo_data)
+
+    @mcp.tool()
+    async def nc_calendar_update_todo(
+        calendar_name: str,
+        todo_uid: str,
+        ctx: Context,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        status: Optional[str] = None,
+        priority: Optional[int] = None,
+        percent_complete: Optional[int] = None,
+        due: Optional[str] = None,
+        dtstart: Optional[str] = None,
+        completed: Optional[str] = None,
+        categories: Optional[str] = None,
+    ):
+        """Update an existing todo/task.
+
+        Args:
+            calendar_name: Name of the calendar containing the todo
+            todo_uid: UID of the todo to update
+            ctx: MCP context
+            summary: New summary/title
+            description: New description
+            status: New status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
+            priority: New priority (0-9)
+            percent_complete: New completion percentage (0-100)
+            due: New due date/time (ISO format)
+            dtstart: New start date/time (ISO format)
+            completed: Completion timestamp (ISO format)
+            categories: New categories (comma-separated)
+
+        Returns:
+            Dict with todo update result
+        """
+        client = get_client(ctx)
+
+        # Build update data with only non-None values
+        todo_data = {}
+        if summary is not None:
+            todo_data["summary"] = summary
+        if description is not None:
+            todo_data["description"] = description
+        if status is not None:
+            todo_data["status"] = status
+        if priority is not None:
+            todo_data["priority"] = priority
+        if percent_complete is not None:
+            todo_data["percent_complete"] = percent_complete
+        if due is not None:
+            todo_data["due"] = due
+        if dtstart is not None:
+            todo_data["dtstart"] = dtstart
+        if completed is not None:
+            todo_data["completed"] = completed
+        if categories is not None:
+            todo_data["categories"] = categories
+
+        return await client.calendar.update_todo(calendar_name, todo_uid, todo_data)
+
+    @mcp.tool()
+    async def nc_calendar_delete_todo(
+        calendar_name: str,
+        todo_uid: str,
+        ctx: Context,
+    ):
+        """Delete a todo/task from a calendar.
+
+        Args:
+            calendar_name: Name of the calendar containing the todo
+            todo_uid: UID of the todo to delete
+            ctx: MCP context
+
+        Returns:
+            Dict with deletion status
+        """
+        client = get_client(ctx)
+        return await client.calendar.delete_todo(calendar_name, todo_uid)
+
+    @mcp.tool()
+    async def nc_calendar_search_todos(
+        ctx: Context,
+        status: Optional[str] = None,
+        min_priority: Optional[int] = None,
+        categories: Optional[str] = None,
+        summary_contains: Optional[str] = None,
+    ):
+        """Search todos across all calendars with optional filtering.
+
+        Args:
+            ctx: MCP context
+            status: Filter by status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
+            min_priority: Filter by minimum priority (1=highest, 9=lowest)
+            categories: Filter by categories (comma-separated, e.g., "work,urgent")
+            summary_contains: Filter todos where summary contains this text
+
+        Returns:
+            List of todos matching the filters from all calendars
+        """
+        client = get_client(ctx)
+
+        # Build filters dictionary
+        filters = {}
+        if status is not None:
+            filters["status"] = status
+        if min_priority is not None:
+            filters["min_priority"] = min_priority
+        if categories is not None:
+            filters["categories"] = [cat.strip() for cat in categories.split(",")]
+        if summary_contains is not None:
+            filters["summary_contains"] = summary_contains
+
+        todos_data = await client.calendar.search_todos_across_calendars(
+            filters if filters else None
+        )
+
+        todos = [Todo(**todo_data) for todo_data in todos_data]
+        return ListTodosResponse(todos=todos, total_count=len(todos))

nextcloud_mcp_server/server/contacts.py

@@ -2,7 +2,7 @@ import logging
 
 from mcp.server.fastmcp import Context, FastMCP
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 
 logger = logging.getLogger(__name__)
 
@@ -12,13 +12,13 @@ def configure_contacts_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_contacts_list_addressbooks(ctx: Context):
         """List all addressbooks for the user."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.list_addressbooks()
 
     @mcp.tool()
     async def nc_contacts_list_contacts(ctx: Context, *, addressbook: str):
         """List all contacts in the specified addressbook."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.list_contacts(addressbook=addressbook)
 
     @mcp.tool()
@@ -31,7 +31,7 @@ def configure_contacts_tools(mcp: FastMCP):
             name: The name of the addressbook.
             display_name: The display name of the addressbook.
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.create_addressbook(
             name=name, display_name=display_name
         )
@@ -39,7 +39,7 @@ def configure_contacts_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_contacts_delete_addressbook(ctx: Context, *, name: str):
         """Delete an addressbook."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.delete_addressbook(name=name)
 
     @mcp.tool()
@@ -53,7 +53,7 @@ def configure_contacts_tools(mcp: FastMCP):
             uid: The unique ID for the contact.
             contact_data: A dictionary with the contact's details, e.g. {"fn": "John Doe", "email": "john.doe@example.com"}.
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.create_contact(
             addressbook=addressbook, uid=uid, contact_data=contact_data
         )
@@ -61,7 +61,7 @@ def configure_contacts_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_contacts_delete_contact(ctx: Context, *, addressbook: str, uid: str):
         """Delete a contact."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.delete_contact(addressbook=addressbook, uid=uid)
 
     @mcp.tool()
@@ -76,7 +76,7 @@ def configure_contacts_tools(mcp: FastMCP):
             contact_data: A dictionary with the contact's updated details, e.g. {"fn": "Jane Doe", "email": "jane.doe@example.com"}.
             etag: Optional ETag for optimistic concurrency control.
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.update_contact(
             addressbook=addressbook, uid=uid, contact_data=contact_data, etag=etag
         )

nextcloud_mcp_server/server/cookbook.py

@@ -0,0 +1,594 @@
+import logging
+
+from httpx import HTTPStatusError, RequestError
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.shared.exceptions import McpError
+from mcp.types import ErrorData
+
+from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.models.cookbook import (
+    Category,
+    CookbookConfig,
+    CreateRecipeResponse,
+    DeleteRecipeResponse,
+    ImportRecipeResponse,
+    Keyword,
+    ListCategoriesResponse,
+    ListKeywordsResponse,
+    ListRecipesResponse,
+    Recipe,
+    RecipeStub,
+    ReindexResponse,
+    SearchRecipesResponse,
+    UpdateRecipeResponse,
+    Version,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def configure_cookbook_tools(mcp: FastMCP):
+    @mcp.resource("cookbook://version")
+    async def cookbook_get_version():
+        """Get the Cookbook app and API version"""
+        ctx: Context = mcp.get_context()
+        client = get_client(ctx)
+        version_data = await client.cookbook.get_version()
+        return Version(**version_data)
+
+    @mcp.resource("cookbook://config")
+    async def cookbook_get_config():
+        """Get the Cookbook app configuration"""
+        ctx: Context = mcp.get_context()
+        client = get_client(ctx)
+        config_data = await client.cookbook.get_config()
+        return CookbookConfig(**config_data)
+
+    @mcp.resource("nc://Cookbook/{recipe_id}")
+    async def nc_cookbook_get_recipe_resource(recipe_id: int):
+        """Get a recipe by ID using resource URI"""
+        ctx: Context = mcp.get_context()
+        client = get_client(ctx)
+        try:
+            recipe_data = await client.cookbook.get_recipe(recipe_id)
+            return Recipe(**recipe_data)
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise McpError(
+                    ErrorData(code=-1, message=f"Recipe {recipe_id} not found")
+                )
+            elif e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(code=-1, message=f"Access denied to recipe {recipe_id}")
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to retrieve recipe {recipe_id}: {e.response.reason_phrase}",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_import_recipe(url: str, ctx: Context) -> ImportRecipeResponse:
+        """Import a recipe from a URL using schema.org metadata.
+
+        This extracts recipe data from websites that use schema.org Recipe markup.
+        Many popular recipe sites support this standard."""
+        client = get_client(ctx)
+        try:
+            recipe_data = await client.cookbook.import_recipe(url)
+            recipe = Recipe(**recipe_data)
+            return ImportRecipeResponse(
+                recipe=recipe,
+                recipe_id=recipe.id or "unknown",
+            )
+        except RequestError as e:
+            # RequestError can have empty str() - get details from exception attributes
+            error_detail = (
+                str(e)
+                or f"{type(e).__name__}: {getattr(e, '__cause__', 'unknown cause')}"
+            )
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Network error importing recipe from {url}: {error_detail}",
+                )
+            )
+        except HTTPStatusError as e:
+            if e.response.status_code == 400:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Invalid URL or missing 'url' field: {url}",
+                    )
+                )
+            elif e.response.status_code == 409:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="A recipe with this name already exists. Import aborted.",
+                    )
+                )
+            elif e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to import recipes",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to import recipe from {url}: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_list_recipes(ctx: Context) -> ListRecipesResponse:
+        """Get all recipes in the database"""
+        client = get_client(ctx)
+        try:
+            recipes_data = await client.cookbook.list_recipes()
+            recipes = [RecipeStub(**r) for r in recipes_data]
+            return ListRecipesResponse(recipes=recipes, total_count=len(recipes))
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to list recipes",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to list recipes: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_get_recipe(recipe_id: int, ctx: Context) -> Recipe:
+        """Get a specific recipe by its ID"""
+        client = get_client(ctx)
+        try:
+            recipe_data = await client.cookbook.get_recipe(recipe_id)
+            return Recipe(**recipe_data)
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise McpError(
+                    ErrorData(code=-1, message=f"Recipe {recipe_id} not found")
+                )
+            elif e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(code=-1, message=f"Access denied to recipe {recipe_id}")
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to retrieve recipe {recipe_id}: {e.response.reason_phrase}",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_create_recipe(
+        name: str,
+        description: str | None = None,
+        ingredients: list[str] | None = None,
+        instructions: list[str] | None = None,
+        url: str | None = None,
+        prep_time: str | None = None,
+        cook_time: str | None = None,
+        total_time: str | None = None,
+        recipe_yield: int | None = None,
+        category: str | None = None,
+        keywords: str | None = None,
+        ctx: Context = None,
+    ) -> CreateRecipeResponse:
+        """Create a new recipe.
+
+        Required: name
+        Optional: All other recipe fields following schema.org/Recipe format.
+
+        Times should be in ISO8601 duration format (e.g., 'PT30M' for 30 minutes)."""
+        client = get_client(ctx)
+
+        recipe_data = {"name": name}
+        if description:
+            recipe_data["description"] = description
+        if ingredients:
+            recipe_data["recipeIngredient"] = ingredients
+        if instructions:
+            recipe_data["recipeInstructions"] = instructions
+        if url:
+            recipe_data["url"] = url
+        if prep_time:
+            recipe_data["prepTime"] = prep_time
+        if cook_time:
+            recipe_data["cookTime"] = cook_time
+        if total_time:
+            recipe_data["totalTime"] = total_time
+        if recipe_yield:
+            recipe_data["recipeYield"] = recipe_yield
+        if category:
+            recipe_data["recipeCategory"] = category
+        if keywords:
+            recipe_data["keywords"] = keywords
+
+        try:
+            recipe_id = await client.cookbook.create_recipe(recipe_data)
+            return CreateRecipeResponse(id=recipe_id)
+        except HTTPStatusError as e:
+            if e.response.status_code == 409:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"A recipe with name '{name}' already exists",
+                    )
+                )
+            elif e.response.status_code == 422:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Recipe name is required and cannot be empty",
+                    )
+                )
+            elif e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to create recipes",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to create recipe: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_update_recipe(
+        recipe_id: int,
+        name: str | None = None,
+        description: str | None = None,
+        ingredients: list[str] | None = None,
+        instructions: list[str] | None = None,
+        url: str | None = None,
+        prep_time: str | None = None,
+        cook_time: str | None = None,
+        total_time: str | None = None,
+        recipe_yield: int | None = None,
+        category: str | None = None,
+        keywords: str | None = None,
+        ctx: Context = None,
+    ) -> UpdateRecipeResponse:
+        """Update an existing recipe.
+
+        Provide only the fields you want to update. Unspecified fields remain unchanged."""
+        client = get_client(ctx)
+
+        # First get the current recipe
+        try:
+            current_recipe = await client.cookbook.get_recipe(recipe_id)
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise McpError(
+                    ErrorData(code=-1, message=f"Recipe {recipe_id} not found")
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to fetch recipe {recipe_id}: {e.response.reason_phrase}",
+                    )
+                )
+
+        # Update only specified fields
+        recipe_data = current_recipe.copy()
+        if name is not None:
+            recipe_data["name"] = name
+        if description is not None:
+            recipe_data["description"] = description
+        if ingredients is not None:
+            recipe_data["recipeIngredient"] = ingredients
+        if instructions is not None:
+            recipe_data["recipeInstructions"] = instructions
+        if url is not None:
+            recipe_data["url"] = url
+        if prep_time is not None:
+            recipe_data["prepTime"] = prep_time
+        if cook_time is not None:
+            recipe_data["cookTime"] = cook_time
+        if total_time is not None:
+            recipe_data["totalTime"] = total_time
+        if recipe_yield is not None:
+            recipe_data["recipeYield"] = recipe_yield
+        if category is not None:
+            recipe_data["recipeCategory"] = category
+        if keywords is not None:
+            recipe_data["keywords"] = keywords
+
+        try:
+            updated_id = await client.cookbook.update_recipe(recipe_id, recipe_data)
+            return UpdateRecipeResponse(id=updated_id)
+        except HTTPStatusError as e:
+            if e.response.status_code == 422:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Recipe name is required and cannot be empty",
+                    )
+                )
+            elif e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Access denied: insufficient permissions to update recipe {recipe_id}",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to update recipe {recipe_id}: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_delete_recipe(
+        recipe_id: int, ctx: Context
+    ) -> DeleteRecipeResponse:
+        """Delete a recipe permanently"""
+        logger.info("Deleting recipe %s", recipe_id)
+        client = get_client(ctx)
+        try:
+            message = await client.cookbook.delete_recipe(recipe_id)
+            return DeleteRecipeResponse(
+                status_code=200,
+                message=message,
+                deleted_id=recipe_id,
+            )
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise McpError(
+                    ErrorData(code=-1, message=f"Recipe {recipe_id} not found")
+                )
+            elif e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Access denied: insufficient permissions to delete recipe {recipe_id}",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to delete recipe {recipe_id}: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_search_recipes(
+        query: str, ctx: Context
+    ) -> SearchRecipesResponse:
+        """Search for recipes by keywords, tags, and categories"""
+        client = get_client(ctx)
+        try:
+            recipes_data = await client.cookbook.search_recipes(query)
+            recipes = [RecipeStub(**r) for r in recipes_data]
+            return SearchRecipesResponse(
+                recipes=recipes, query=query, total_found=len(recipes)
+            )
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to search recipes",
+                    )
+                )
+            elif e.response.status_code == 500:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Search failed: server error",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Search failed: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_list_categories(ctx: Context) -> ListCategoriesResponse:
+        """Get all known categories.
+
+        Note: A category name of '*' indicates recipes with no category."""
+        client = get_client(ctx)
+        try:
+            categories_data = await client.cookbook.list_categories()
+            categories = [Category(**c) for c in categories_data]
+            return ListCategoriesResponse(categories=categories)
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to list categories",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to list categories: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_get_recipes_in_category(
+        category: str, ctx: Context
+    ) -> ListRecipesResponse:
+        """Get all recipes in a specific category.
+
+        Use '_' as the category name to get recipes with no category."""
+        client = get_client(ctx)
+        try:
+            recipes_data = await client.cookbook.get_recipes_in_category(category)
+            recipes = [RecipeStub(**r) for r in recipes_data]
+            return ListRecipesResponse(recipes=recipes, total_count=len(recipes))
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to access recipes",
+                    )
+                )
+            elif e.response.status_code == 500:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Could not find category '{category}'",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to get recipes in category: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_list_keywords(ctx: Context) -> ListKeywordsResponse:
+        """Get all known keywords/tags"""
+        client = get_client(ctx)
+        try:
+            keywords_data = await client.cookbook.list_keywords()
+            keywords = [Keyword(**k) for k in keywords_data]
+            return ListKeywordsResponse(keywords=keywords)
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to list keywords",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to list keywords: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_get_recipes_with_keywords(
+        keywords: list[str], ctx: Context
+    ) -> ListRecipesResponse:
+        """Get all recipes that have specific keywords/tags"""
+        client = get_client(ctx)
+        try:
+            recipes_data = await client.cookbook.get_recipes_with_keywords(keywords)
+            recipes = [RecipeStub(**r) for r in recipes_data]
+            return ListRecipesResponse(recipes=recipes, total_count=len(recipes))
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to access recipes",
+                    )
+                )
+            elif e.response.status_code == 500:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Failed to get recipes with keywords: server error",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to get recipes with keywords: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_set_config(
+        folder: str | None = None,
+        update_interval: int | None = None,
+        print_image: bool | None = None,
+        ctx: Context = None,
+    ) -> ReindexResponse:
+        """Set Cookbook app configuration.
+
+        Args:
+            folder: Recipe folder path in user's files
+            update_interval: Automatic rescan interval in minutes
+            print_image: Whether to print images with recipes"""
+        client = get_client(ctx)
+
+        config_data = {}
+        if folder is not None:
+            config_data["folder"] = folder
+        if update_interval is not None:
+            config_data["update_interval"] = update_interval
+        if print_image is not None:
+            config_data["print_image"] = print_image
+
+        try:
+            result = await client.cookbook.set_config(config_data)
+            return ReindexResponse(status_code=200, message=str(result))
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to set configuration",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to set configuration: server error ({e.response.status_code})",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_cookbook_reindex(ctx: Context) -> ReindexResponse:
+        """Trigger a rescan of all recipes into the caching database.
+
+        This rebuilds the search index and should be used after manual file changes."""
+        client = get_client(ctx)
+        try:
+            message = await client.cookbook.reindex()
+            return ReindexResponse(status_code=200, message=message)
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Access denied: insufficient permissions to reindex",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to reindex: server error ({e.response.status_code})",
+                    )
+                )

nextcloud_mcp_server/server/deck.py

@@ -3,19 +3,19 @@ from typing import Optional
 
 from mcp.server.fastmcp import Context, FastMCP
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models.deck import (
+    CardOperationResponse,
+    CreateBoardResponse,
+    CreateCardResponse,
+    CreateLabelResponse,
+    CreateStackResponse,
     DeckBoard,
-    DeckStack,
     DeckCard,
     DeckLabel,
-    CreateBoardResponse,
-    CreateStackResponse,
-    StackOperationResponse,
-    CreateCardResponse,
-    CardOperationResponse,
-    CreateLabelResponse,
+    DeckStack,
     LabelOperationResponse,
+    StackOperationResponse,
 )
 
 logger = logging.getLogger(__name__)
@@ -30,7 +30,7 @@ def configure_deck_tools(mcp: FastMCP):
         """List all Nextcloud Deck boards"""
         ctx: Context = mcp.get_context()
         await ctx.warning("This message is deprecated, use the deck_get_board instead")
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         boards = await client.deck.get_boards()
         return [board.model_dump() for board in boards]
 
@@ -41,7 +41,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_board tool instead"
         )
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         board = await client.deck.get_board(board_id)
         return board.model_dump()
 
@@ -52,7 +52,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_stacks tool instead"
         )
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         stacks = await client.deck.get_stacks(board_id)
         return [stack.model_dump() for stack in stacks]
 
@@ -63,7 +63,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_stack tool instead"
         )
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         return stack.model_dump()
 
@@ -74,7 +74,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_cards tool instead"
         )
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         if stack.cards:
             return [card.model_dump() for card in stack.cards]
@@ -87,7 +87,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_card tool instead"
         )
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         card = await client.deck.get_card(board_id, stack_id, card_id)
         return card.model_dump()
 
@@ -98,7 +98,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_labels tool instead"
         )
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         board = await client.deck.get_board(board_id)
         return [label.model_dump() for label in board.labels]
 
@@ -109,7 +109,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_label tool instead"
         )
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         label = await client.deck.get_label(board_id, label_id)
         return label.model_dump()
 
@@ -118,28 +118,28 @@ def configure_deck_tools(mcp: FastMCP):
     @mcp.tool()
     async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
         """Get all Nextcloud Deck boards"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         boards = await client.deck.get_boards()
         return boards
 
     @mcp.tool()
     async def deck_get_board(ctx: Context, board_id: int) -> DeckBoard:
         """Get details of a specific Nextcloud Deck board"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         board = await client.deck.get_board(board_id)
         return board
 
     @mcp.tool()
     async def deck_get_stacks(ctx: Context, board_id: int) -> list[DeckStack]:
         """Get all stacks in a Nextcloud Deck board"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         stacks = await client.deck.get_stacks(board_id)
         return stacks
 
     @mcp.tool()
     async def deck_get_stack(ctx: Context, board_id: int, stack_id: int) -> DeckStack:
         """Get details of a specific Nextcloud Deck stack"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         return stack
 
@@ -148,7 +148,7 @@ def configure_deck_tools(mcp: FastMCP):
         ctx: Context, board_id: int, stack_id: int
     ) -> list[DeckCard]:
         """Get all cards in a Nextcloud Deck stack"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         if stack.cards:
             return stack.cards
@@ -159,21 +159,21 @@ def configure_deck_tools(mcp: FastMCP):
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> DeckCard:
         """Get details of a specific Nextcloud Deck card"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         card = await client.deck.get_card(board_id, stack_id, card_id)
         return card
 
     @mcp.tool()
     async def deck_get_labels(ctx: Context, board_id: int) -> list[DeckLabel]:
         """Get all labels in a Nextcloud Deck board"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         board = await client.deck.get_board(board_id)
         return board.labels
 
     @mcp.tool()
     async def deck_get_label(ctx: Context, board_id: int, label_id: int) -> DeckLabel:
         """Get details of a specific Nextcloud Deck label"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         label = await client.deck.get_label(board_id, label_id)
         return label
 
@@ -189,7 +189,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: The title of the new board
             color: The hexadecimal color of the new board (e.g. FF0000)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         board = await client.deck.create_board(title, color)
         return CreateBoardResponse(id=board.id, title=board.title, color=board.color)
 
@@ -206,7 +206,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: The title of the new stack
             order: Order for sorting the stacks
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         stack = await client.deck.create_stack(board_id, title, order)
         return CreateStackResponse(id=stack.id, title=stack.title, order=stack.order)
 
@@ -226,7 +226,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: New title for the stack
             order: New order for the stack
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.update_stack(board_id, stack_id, title, order)
         return StackOperationResponse(
             success=True,
@@ -245,7 +245,7 @@ def configure_deck_tools(mcp: FastMCP):
             board_id: The ID of the board
             stack_id: The ID of the stack
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.delete_stack(board_id, stack_id)
         return StackOperationResponse(
             success=True,
@@ -277,7 +277,7 @@ def configure_deck_tools(mcp: FastMCP):
             description: Description of the card
             duedate: Due date of the card (ISO-8601 format)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         card = await client.deck.create_card(
             board_id, stack_id, title, type, order, description, duedate
         )
@@ -318,7 +318,7 @@ def configure_deck_tools(mcp: FastMCP):
             archived: Whether the card should be archived
             done: Completion date for the card (ISO-8601 format)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.update_card(
             board_id,
             stack_id,
@@ -351,7 +351,7 @@ def configure_deck_tools(mcp: FastMCP):
             stack_id: The ID of the stack
             card_id: The ID of the card
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.delete_card(board_id, stack_id, card_id)
         return CardOperationResponse(
             success=True,
@@ -372,7 +372,7 @@ def configure_deck_tools(mcp: FastMCP):
             stack_id: The ID of the stack
             card_id: The ID of the card
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.archive_card(board_id, stack_id, card_id)
         return CardOperationResponse(
             success=True,
@@ -393,7 +393,7 @@ def configure_deck_tools(mcp: FastMCP):
             stack_id: The ID of the stack
             card_id: The ID of the card
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.unarchive_card(board_id, stack_id, card_id)
         return CardOperationResponse(
             success=True,
@@ -421,7 +421,7 @@ def configure_deck_tools(mcp: FastMCP):
             order: New position in the target stack
             target_stack_id: The ID of the target stack
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.reorder_card(
             board_id, stack_id, card_id, order, target_stack_id
         )
@@ -445,7 +445,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: The title of the new label
             color: The color of the new label (hex format without #)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         label = await client.deck.create_label(board_id, title, color)
         return CreateLabelResponse(id=label.id, title=label.title, color=label.color)
 
@@ -465,7 +465,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: New title for the label
             color: New color for the label (hex format without #)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.update_label(board_id, label_id, title, color)
         return LabelOperationResponse(
             success=True,
@@ -484,7 +484,7 @@ def configure_deck_tools(mcp: FastMCP):
             board_id: The ID of the board
             label_id: The ID of the label
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.delete_label(board_id, label_id)
         return LabelOperationResponse(
             success=True,
@@ -506,7 +506,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             label_id: The ID of the label to assign
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.assign_label_to_card(board_id, stack_id, card_id, label_id)
         return CardOperationResponse(
             success=True,
@@ -528,7 +528,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             label_id: The ID of the label to remove
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.remove_label_from_card(board_id, stack_id, card_id, label_id)
         return CardOperationResponse(
             success=True,
@@ -551,7 +551,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             user_id: The user ID to assign
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.assign_user_to_card(board_id, stack_id, card_id, user_id)
         return CardOperationResponse(
             success=True,
@@ -573,7 +573,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             user_id: The user ID to unassign
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.unassign_user_from_card(board_id, stack_id, card_id, user_id)
         return CardOperationResponse(
             success=True,

nextcloud_mcp_server/server/notes.py

@@ -1,20 +1,20 @@
 import logging
-from httpx import HTTPStatusError
+
+from httpx import HTTPStatusError, RequestError
+from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
 from mcp.types import ErrorData
 
-from mcp.server.fastmcp import Context, FastMCP
-
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models.notes import (
-    Note,
-    NotesSettings,
-    CreateNoteResponse,
-    UpdateNoteResponse,
-    DeleteNoteResponse,
     AppendContentResponse,
-    SearchNotesResponse,
+    CreateNoteResponse,
+    DeleteNoteResponse,
+    Note,
     NoteSearchResult,
+    NotesSettings,
+    SearchNotesResponse,
+    UpdateNoteResponse,
 )
 
 logger = logging.getLogger(__name__)
@@ -27,7 +27,7 @@ def configure_notes_tools(mcp: FastMCP):
         ctx: Context = (
             mcp.get_context()
         )  # https://github.com/modelcontextprotocol/python-sdk/issues/244
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         settings_data = await client.notes.get_settings()
         return NotesSettings(**settings_data)
 
@@ -35,7 +35,7 @@ def configure_notes_tools(mcp: FastMCP):
     async def nc_notes_get_attachment_resource(note_id: int, attachment_filename: str):
         """Get a specific attachment from a note"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         # Assuming a method get_note_attachment exists in the client
         # This method should return the raw content and determine the mime type
         content, mime_type = await client.webdav.get_note_attachment(
@@ -57,10 +57,17 @@ def configure_notes_tools(mcp: FastMCP):
         """Get user note using note id"""
 
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             note_data = await client.notes.get_note(note_id)
             return Note(**note_data)
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Network error retrieving note {note_id}: {str(e)}",
+                )
+            )
         except HTTPStatusError as e:
             if e.response.status_code == 404:
                 raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
@@ -81,7 +88,7 @@ def configure_notes_tools(mcp: FastMCP):
         title: str, content: str, category: str, ctx: Context
     ) -> CreateNoteResponse:
         """Create a new note"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             note_data = await client.notes.create_note(
                 title=title,
@@ -92,6 +99,10 @@ def configure_notes_tools(mcp: FastMCP):
             return CreateNoteResponse(
                 id=note.id, title=note.title, category=note.category, etag=note.etag
             )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(code=-1, message=f"Network error creating note: {str(e)}")
+            )
         except HTTPStatusError as e:
             if e.response.status_code == 403:
                 raise McpError(
@@ -133,7 +144,7 @@ def configure_notes_tools(mcp: FastMCP):
         If the note has been modified by someone else since you retrieved it,
         the update will fail with a 412 error."""
         logger.info("Updating note %s", note_id)
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             note_data = await client.notes.update(
                 note_id=note_id,
@@ -146,6 +157,12 @@ def configure_notes_tools(mcp: FastMCP):
             return UpdateNoteResponse(
                 id=note.id, title=note.title, category=note.category, etag=note.etag
             )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1, message=f"Network error updating note {note_id}: {str(e)}"
+                )
+            )
         except HTTPStatusError as e:
             if e.response.status_code == 404:
                 raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
@@ -183,7 +200,7 @@ def configure_notes_tools(mcp: FastMCP):
         between the note and what will be appended."""
 
         logger.info("Appending content to note %s", note_id)
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             note_data = await client.notes.append_content(
                 note_id=note_id, content=content
@@ -192,6 +209,13 @@ def configure_notes_tools(mcp: FastMCP):
             return AppendContentResponse(
                 id=note.id, title=note.title, category=note.category, etag=note.etag
             )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Network error appending to note {note_id}: {str(e)}",
+                )
+            )
         except HTTPStatusError as e:
             if e.response.status_code == 404:
                 raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
@@ -220,7 +244,7 @@ def configure_notes_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
         """Search notes by title or content, returning only id, title, and category."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             search_results_raw = await client.notes_search_notes(query=query)
 
@@ -238,6 +262,10 @@ def configure_notes_tools(mcp: FastMCP):
             return SearchNotesResponse(
                 results=results, query=query, total_found=len(results)
             )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(code=-1, message=f"Network error searching notes: {str(e)}")
+            )
         except HTTPStatusError as e:
             if e.response.status_code == 403:
                 raise McpError(
@@ -261,10 +289,16 @@ def configure_notes_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_notes_get_note(note_id: int, ctx: Context) -> Note:
         """Get a specific note by its ID"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             note_data = await client.notes.get_note(note_id)
             return Note(**note_data)
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1, message=f"Network error getting note {note_id}: {str(e)}"
+                )
+            )
         except HTTPStatusError as e:
             if e.response.status_code == 404:
                 raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
@@ -285,7 +319,7 @@ def configure_notes_tools(mcp: FastMCP):
         note_id: int, attachment_filename: str, ctx: Context
     ) -> dict[str, str]:
         """Get a specific attachment from a note"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             content, mime_type = await client.webdav.get_note_attachment(
                 note_id=note_id, filename=attachment_filename
@@ -295,6 +329,13 @@ def configure_notes_tools(mcp: FastMCP):
                 "mimeType": mime_type,
                 "data": content,
             }
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Network error getting attachment {attachment_filename} for note {note_id}: {str(e)}",
+                )
+            )
         except HTTPStatusError as e:
             if e.response.status_code == 404:
                 raise McpError(
@@ -322,7 +363,7 @@ def configure_notes_tools(mcp: FastMCP):
     async def nc_notes_delete_note(note_id: int, ctx: Context) -> DeleteNoteResponse:
         """Delete a note permanently"""
         logger.info("Deleting note %s", note_id)
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             await client.notes.delete_note(note_id)
             return DeleteNoteResponse(
@@ -330,6 +371,12 @@ def configure_notes_tools(mcp: FastMCP):
                 message=f"Note {note_id} deleted successfully",
                 deleted_id=note_id,
             )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1, message=f"Network error deleting note {note_id}: {str(e)}"
+                )
+            )
         except HTTPStatusError as e:
             if e.response.status_code == 404:
                 raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))

nextcloud_mcp_server/server/sharing.py

@@ -0,0 +1,134 @@
+"""MCP tools for Nextcloud file/folder sharing operations."""
+
+import json
+
+from mcp.server.fastmcp import Context, FastMCP
+
+from nextcloud_mcp_server.context import get_client
+
+
+def configure_sharing_tools(mcp: FastMCP):
+    """Configure sharing-related MCP tools.
+
+    Args:
+        mcp: FastMCP server instance
+    """
+
+    @mcp.tool()
+    async def nc_share_create(
+        path: str,
+        share_with: str,
+        ctx: Context,
+        share_type: int = 0,
+        permissions: int = 1,
+    ) -> str:
+        """Create a share for a file or folder in Nextcloud.
+
+        Share a file or folder with another user or group. The authenticated user
+        must own the file/folder being shared.
+
+        Args:
+            path: Path to file/folder to share (relative to your files, e.g., "/document.txt")
+            share_with: Username (for user share) or group name (for group share)
+            share_type: Share type - 0 for user (default), 1 for group, 3 for public link
+            permissions: Share permissions (default: 1 for read-only):
+                - 1 = read
+                - 2 = update
+                - 4 = create
+                - 8 = delete
+                - 16 = share
+                - 31 = all permissions
+                Common: 1 (read-only), 3 (read+update), 15 (read+update+create+delete)
+
+        Returns:
+            JSON string with share information including share ID
+        """
+        client = get_client(ctx)
+        share_data = await client.sharing.create_share(
+            path=path,
+            share_with=share_with,
+            share_type=share_type,
+            permissions=permissions,
+        )
+        return json.dumps(share_data, indent=2)
+
+    @mcp.tool()
+    async def nc_share_delete(share_id: int, ctx: Context) -> str:
+        """Delete a share by its ID.
+
+        Remove a share that you created. You must be the owner of the share.
+
+        Args:
+            share_id: The ID of the share to delete
+
+        Returns:
+            JSON string confirming deletion
+        """
+        client = get_client(ctx)
+        await client.sharing.delete_share(share_id)
+        return json.dumps(
+            {"success": True, "message": f"Share {share_id} deleted"}, indent=2
+        )
+
+    @mcp.tool()
+    async def nc_share_get(share_id: int, ctx: Context) -> str:
+        """Get information about a specific share.
+
+        Retrieve details about a share by its ID. You must have access to the share
+        (either as owner or recipient).
+
+        Args:
+            share_id: The ID of the share
+
+        Returns:
+            JSON string with share information
+        """
+        client = get_client(ctx)
+        share_data = await client.sharing.get_share(share_id)
+        return json.dumps(share_data, indent=2)
+
+    @mcp.tool()
+    async def nc_share_list(
+        ctx: Context, path: str | None = None, shared_with_me: bool = False
+    ) -> str:
+        """List shares created by you or shared with you.
+
+        Args:
+            path: Optional path to filter shares for a specific file/folder
+            shared_with_me: If True, list shares that others shared with you.
+                          If False (default), list shares you created.
+
+        Returns:
+            JSON string with list of shares
+        """
+        client = get_client(ctx)
+        shares = await client.sharing.list_shares(
+            path=path, shared_with_me=shared_with_me
+        )
+        return json.dumps(shares, indent=2)
+
+    @mcp.tool()
+    async def nc_share_update(share_id: int, permissions: int, ctx: Context) -> str:
+        """Update the permissions of an existing share.
+
+        Modify the permissions for a share you created. You must be the owner.
+
+        Args:
+            share_id: The ID of the share to update
+            permissions: New permissions value:
+                - 1 = read
+                - 2 = update
+                - 4 = create
+                - 8 = delete
+                - 16 = share
+                - 31 = all permissions
+                Common: 1 (read-only), 3 (read+update), 15 (read+update+create+delete)
+
+        Returns:
+            JSON string with updated share information
+        """
+        client = get_client(ctx)
+        share_data = await client.sharing.update_share(
+            share_id=share_id, permissions=permissions
+        )
+        return json.dumps(share_data, indent=2)

nextcloud_mcp_server/server/tables.py

@@ -2,7 +2,7 @@ import logging
 
 from mcp.server.fastmcp import Context, FastMCP
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 
 logger = logging.getLogger(__name__)
 
@@ -12,13 +12,13 @@ def configure_tables_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_tables_list_tables(ctx: Context):
         """List all tables available to the user"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.list_tables()
 
     @mcp.tool()
     async def nc_tables_get_schema(table_id: int, ctx: Context):
         """Get the schema/structure of a specific table including columns and views"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.get_table_schema(table_id)
 
     @mcp.tool()
@@ -29,7 +29,7 @@ def configure_tables_tools(mcp: FastMCP):
         offset: int | None = None,
     ):
         """Read rows from a table with optional pagination"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.get_table_rows(table_id, limit, offset)
 
     @mcp.tool()
@@ -38,7 +38,7 @@ def configure_tables_tools(mcp: FastMCP):
 
         Data should be a dictionary mapping column IDs to values, e.g. {1: "text", 2: 42}
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.create_row(table_id, data)
 
     @mcp.tool()
@@ -47,11 +47,11 @@ def configure_tables_tools(mcp: FastMCP):
 
         Data should be a dictionary mapping column IDs to new values, e.g. {1: "new text", 2: 99}
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.update_row(row_id, data)
 
     @mcp.tool()
     async def nc_tables_delete_row(row_id: int, ctx: Context):
         """Delete a row from a table"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.delete_row(row_id)

nextcloud_mcp_server/server/webdav.py

@@ -8,6 +8,8 @@ from nextcloud_mcp_server.utils.document_parser import (
     parse_document,
 )
 from nextcloud_mcp_server.config import is_unstructured_parsing_enabled
+from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.models import FileInfo, SearchFilesResponse
 
 logger = logging.getLogger(__name__)
 
@@ -23,15 +25,8 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             List of items with metadata including name, path, is_directory, size, content_type, last_modified
-
-        Examples:
-            # List root directory
-            await nc_webdav_list_directory("")
-
-            # List a specific folder
-            await nc_webdav_list_directory("Documents/Projects")
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.list_directory(path)
 
     @mcp.tool()
@@ -61,7 +56,7 @@ def configure_webdav_tools(mcp: FastMCP):
             result = await nc_webdav_read_file("Images/photo.jpg")
             logger.info(result['encoding'])  # 'base64'
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         content, content_type = await client.webdav.read_file(path)
 
         # Check if this is a parseable document (PDF, DOCX, etc.)
@@ -122,15 +117,8 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code indicating success
-
-        Examples:
-            # Write a text file
-            await nc_webdav_write_file("Documents/notes.md", "# My Notes\nContent here...")
-
-            # Write binary data (base64 encoded)
-            await nc_webdav_write_file("files/data.bin", base64_content, "application/octet-stream;base64")
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Handle base64 encoded content
         if content_type and "base64" in content_type.lower():
@@ -152,15 +140,8 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code (201 for created, 405 if already exists)
-
-        Examples:
-            # Create a single directory
-            await nc_webdav_create_directory("NewProject")
-
-            # Create nested directories (parent must exist)
-            await nc_webdav_create_directory("Projects/MyApp/docs")
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.create_directory(path)
 
     @mcp.tool()
@@ -172,15 +153,8 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code indicating result (404 if not found)
-
-        Examples:
-            # Delete a file
-            await nc_webdav_delete_resource("old_document.txt")
-
-            # Delete a directory (will delete all contents)
-            await nc_webdav_delete_resource("temp_folder")
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.delete_resource(path)
 
     @mcp.tool()
@@ -196,21 +170,8 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code indicating result (404 if source not found, 412 if destination exists and overwrite is False)
-
-        Examples:
-            # Rename a file
-            await nc_webdav_move_resource("document.txt", "new_name.txt")
-
-            # Move a file to another directory
-            await nc_webdav_move_resource("document.txt", "Archive/document.txt")
-
-            # Move a directory
-            await nc_webdav_move_resource("Projects/OldProject", "Projects/NewProject")
-
-            # Move and overwrite if destination exists
-            await nc_webdav_move_resource("document.txt", "Archive/document.txt", overwrite=True)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.move_resource(
             source_path, destination_path, overwrite
         )
@@ -228,21 +189,198 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code indicating result (404 if source not found, 412 if destination exists and overwrite is False)
-
-        Examples:
-            # Copy a file
-            await nc_webdav_copy_resource("document.txt", "document_copy.txt")
-
-            # Copy a file to another directory
-            await nc_webdav_copy_resource("document.txt", "Backup/document.txt")
-
-            # Copy a directory
-            await nc_webdav_copy_resource("Projects/ProjectA", "Projects/ProjectA_Backup")
-
-            # Copy and overwrite if destination exists
-            await nc_webdav_copy_resource("document.txt", "Backup/document.txt", overwrite=True)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.copy_resource(
             source_path, destination_path, overwrite
         )
+
+    @mcp.tool()
+    async def nc_webdav_search_files(
+        ctx: Context,
+        scope: str = "",
+        name_pattern: str | None = None,
+        mime_type: str | None = None,
+        only_favorites: bool = False,
+        limit: int | None = None,
+    ) -> SearchFilesResponse:
+        """Search for files in NextCloud using WebDAV SEARCH.
+
+        This is a high-level search tool that supports common search patterns.
+        For more complex queries, use the specific search tools.
+
+        Args:
+            scope: Directory path to search in (empty string for user root)
+            name_pattern: File name pattern (supports % wildcard, e.g., "%.txt" for all text files)
+            mime_type: MIME type to filter by (supports % wildcard, e.g., "image/%" for all images)
+            only_favorites: If True, only return favorited files
+            limit: Maximum number of results to return
+
+        Returns:
+            SearchFilesResponse with list of matching files
+        """
+        client = get_client(ctx)
+
+        # Build where conditions based on filters
+        conditions = []
+
+        if name_pattern:
+            conditions.append(
+                f"""
+                <d:like>
+                    <d:prop>
+                        <d:displayname/>
+                    </d:prop>
+                    <d:literal>{name_pattern}</d:literal>
+                </d:like>
+            """
+            )
+
+        if mime_type:
+            conditions.append(
+                f"""
+                <d:like>
+                    <d:prop>
+                        <d:getcontenttype/>
+                    </d:prop>
+                    <d:literal>{mime_type}</d:literal>
+                </d:like>
+            """
+            )
+
+        if only_favorites:
+            conditions.append(
+                """
+                <d:eq>
+                    <d:prop>
+                        <oc:favorite/>
+                    </d:prop>
+                    <d:literal>1</d:literal>
+                </d:eq>
+            """
+            )
+
+        # Combine conditions with AND if multiple
+        if len(conditions) > 1:
+            where_conditions = f"""
+                <d:and>
+                    {"".join(conditions)}
+                </d:and>
+            """
+        elif len(conditions) == 1:
+            where_conditions = conditions[0]
+        else:
+            where_conditions = None
+
+        # Include extended properties
+        properties = [
+            "displayname",
+            "getcontentlength",
+            "getcontenttype",
+            "getlastmodified",
+            "resourcetype",
+            "getetag",
+            "fileid",
+            "favorite",
+        ]
+
+        results = await client.webdav.search_files(
+            scope=scope,
+            where_conditions=where_conditions,
+            properties=properties,
+            limit=limit,
+        )
+
+        # Convert to FileInfo models
+        file_infos = [FileInfo(**result) for result in results]
+
+        # Build filters applied dict
+        filters = {}
+        if name_pattern:
+            filters["name_pattern"] = name_pattern
+        if mime_type:
+            filters["mime_type"] = mime_type
+        if only_favorites:
+            filters["only_favorites"] = True
+
+        return SearchFilesResponse(
+            results=file_infos,
+            total_found=len(file_infos),
+            scope=scope,
+            filters_applied=filters if filters else None,
+        )
+
+    @mcp.tool()
+    async def nc_webdav_find_by_name(
+        pattern: str, ctx: Context, scope: str = "", limit: int | None = None
+    ) -> SearchFilesResponse:
+        """Find files by name pattern in NextCloud.
+
+        Args:
+            pattern: Name pattern to search for (supports % wildcard)
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            SearchFilesResponse with list of matching files
+        """
+        client = get_client(ctx)
+        results = await client.webdav.find_by_name(
+            pattern=pattern, scope=scope, limit=limit
+        )
+        file_infos = [FileInfo(**result) for result in results]
+        return SearchFilesResponse(
+            results=file_infos,
+            total_found=len(file_infos),
+            scope=scope,
+            filters_applied={"name_pattern": pattern},
+        )
+
+    @mcp.tool()
+    async def nc_webdav_find_by_type(
+        mime_type: str, ctx: Context, scope: str = "", limit: int | None = None
+    ) -> SearchFilesResponse:
+        """Find files by MIME type in NextCloud.
+
+        Args:
+            mime_type: MIME type to search for (supports % wildcard)
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            SearchFilesResponse with list of matching files
+        """
+        client = get_client(ctx)
+        results = await client.webdav.find_by_type(
+            mime_type=mime_type, scope=scope, limit=limit
+        )
+        file_infos = [FileInfo(**result) for result in results]
+        return SearchFilesResponse(
+            results=file_infos,
+            total_found=len(file_infos),
+            scope=scope,
+            filters_applied={"mime_type": mime_type},
+        )
+
+    @mcp.tool()
+    async def nc_webdav_list_favorites(
+        ctx: Context, scope: str = "", limit: int | None = None
+    ) -> SearchFilesResponse:
+        """List all favorite files in NextCloud.
+
+        Args:
+            scope: Directory path to search in (empty string for all favorites)
+            limit: Maximum number of results to return
+
+        Returns:
+            SearchFilesResponse with list of favorite files
+        """
+        client = get_client(ctx)
+        results = await client.webdav.list_favorites(scope=scope, limit=limit)
+        file_infos = [FileInfo(**result) for result in results]
+        return SearchFilesResponse(
+            results=file_infos,
+            total_found=len(file_infos),
+            scope=scope,
+            filters_applied={"only_favorites": True},
+        )