From f340380898283d1370a86e3df3fc1443718bdcd6 Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Tue, 7 Apr 2026 23:59:39 +0200 Subject: [PATCH] fix: address third round of review feedback Add BasicAuthLifespanContext Protocol to make the contract between StdioContext and get_client() explicit and type-safe. Document why mcp.get_context() is required for non-template resources. Add News and Collectives to README Supported Apps table, fix transport default. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 6 ++++-- nextcloud_mcp_server/context.py | 14 +++++++++++++- nextcloud_mcp_server/stdio.py | 12 ++++++++---- 3 files changed, 25 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b5664fd9..396cb33b 100644 --- a/README.md +++ b/README.md @@ -85,13 +85,13 @@ docker compose --profile login-flow up -d # Port 8004 ## Key Features -- **90+ MCP Tools** - Comprehensive API coverage across 8 Nextcloud apps +- **110+ MCP Tools** - Comprehensive API coverage across 10 Nextcloud apps - **MCP Resources** - Structured data URIs for browsing Nextcloud data - **Semantic Search (Experimental)** - Optional vector-powered search for Notes, Files, News items, and Deck cards (requires Qdrant + Ollama) - **Document Processing** - OCR and text extraction from PDFs, DOCX, images with progress notifications - **Flexible Deployment** - Docker, Kubernetes ([Helm chart](https://github.com/cbcoutinho/helm-charts)), VM, or local installation - **Production-Ready Auth** - Basic Auth with app passwords (recommended) or OAuth2/OIDC (experimental) -- **Multiple Transports** - stdio (default) and streamable-http +- **Multiple Transports** - streamable-http (default) and stdio ## Supported Apps @@ -105,6 +105,8 @@ docker compose --profile login-flow up -d # Port 8004 | **Cookbook** | 13 | Recipe management, URL import (schema.org) | | **Tables** | 5 | Row operations on Nextcloud Tables | | **Sharing** | 10+ | Create and manage shares | +| **News** | 8 | Feeds, folders, items, feed health monitoring | +| **Collectives** | 16 | Full CRUD on collectives, pages, and tags | | **Semantic Search** | 2+ | Vector search for Notes, Files, News items, and Deck cards (experimental, opt-in, requires infrastructure) | Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request! diff --git a/nextcloud_mcp_server/context.py b/nextcloud_mcp_server/context.py index c94b15be..352a64ac 100644 --- a/nextcloud_mcp_server/context.py +++ b/nextcloud_mcp_server/context.py @@ -1,6 +1,7 @@ """Helper functions for accessing context in MCP tools.""" import logging +from typing import Protocol, runtime_checkable from httpx import BasicAuth from mcp.server.fastmcp import Context @@ -14,6 +15,17 @@ from nextcloud_mcp_server.config import get_settings logger = logging.getLogger(__name__) +@runtime_checkable +class BasicAuthLifespanContext(Protocol): + """Protocol for lifespan contexts that carry a shared NextcloudClient. + + Implemented by :class:`~nextcloud_mcp_server.stdio.StdioContext` and + the single-user lifespan context in ``app.py``. + """ + + client: NextcloudClient + + async def get_client(ctx: Context) -> NextcloudClient: """ Get the appropriate Nextcloud client based on authentication mode. @@ -59,7 +71,7 @@ async def get_client(ctx: Context) -> NextcloudClient: return await _get_client_from_login_flow(ctx, lifespan_ctx.nextcloud_host) # BasicAuth mode - use shared client (no token exchange) - if hasattr(lifespan_ctx, "client"): + if isinstance(lifespan_ctx, BasicAuthLifespanContext): return lifespan_ctx.client # OAuth multi-audience mode (has 'nextcloud_host' attribute) diff --git a/nextcloud_mcp_server/stdio.py b/nextcloud_mcp_server/stdio.py index 152bb18c..4fe1d97c 100644 --- a/nextcloud_mcp_server/stdio.py +++ b/nextcloud_mcp_server/stdio.py @@ -17,6 +17,7 @@ from mcp.server.fastmcp import Context, FastMCP from nextcloud_mcp_server.client import NextcloudClient from nextcloud_mcp_server.config import get_settings from nextcloud_mcp_server.config_validators import AuthMode, validate_configuration +from nextcloud_mcp_server.context import BasicAuthLifespanContext from nextcloud_mcp_server.context import get_client as get_nextcloud_client from nextcloud_mcp_server.server import AVAILABLE_APPS @@ -24,12 +25,12 @@ logger = logging.getLogger(__name__) @dataclass -class StdioContext: +class StdioContext(BasicAuthLifespanContext): """Minimal lifespan context for stdio transport. - Carries only the shared :class:`NextcloudClient`. The ``client`` - attribute satisfies the duck-type check in - :func:`nextcloud_mcp_server.context.get_client`. + Implements :class:`~nextcloud_mcp_server.context.BasicAuthLifespanContext` + so that :func:`~nextcloud_mcp_server.context.get_client` recognises it + as a single-user BasicAuth context. """ client: NextcloudClient @@ -79,6 +80,9 @@ def get_stdio_mcp(enabled_apps: list[str] | None = None) -> FastMCP: mcp = FastMCP("Nextcloud MCP", lifespan=stdio_lifespan) # --- capabilities resource (mirrors app.py) --- + # NOTE: mcp.get_context() is required here because FastMCP's + # FunctionResource (non-template resources) does not support + # context parameter injection — only template resources do. @mcp.resource("nc://capabilities") async def nc_get_capabilities(): """Get the Nextcloud Host capabilities"""