Merge pull request #689 from cbcoutinho/feat/stdio-transport

feat: add stdio transport support for local MCP usage

README.md

@@ -15,7 +15,39 @@ This is a **dedicated standalone MCP server** designed for external MCP clients
 > [!NOTE]
 > **Looking for AI features inside Nextcloud?** Nextcloud also provides [Context Agent](https://github.com/nextcloud/context_agent), which powers the Assistant app and runs as an ExApp inside Nextcloud. See [docs/comparison-context-agent.md](docs/comparison-context-agent.md) for a detailed comparison of use cases.
 
-## Quick Start (Docker)
+## Quick Start
+
+Run the server locally with [uvx](https://docs.astral.sh/uv/) (no installation required):
+
+```bash
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
+NEXTCLOUD_USERNAME=your_username \
+NEXTCLOUD_PASSWORD=your_app_password \
+  uvx nextcloud-mcp-server run --transport stdio
+```
+
+Or add it directly to your MCP client configuration (e.g. `claude_desktop_config.json` or `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "nextcloud": {
+      "command": "uvx",
+      "args": ["nextcloud-mcp-server", "run", "--transport", "stdio"],
+      "env": {
+        "NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
+        "NEXTCLOUD_USERNAME": "your_username",
+        "NEXTCLOUD_PASSWORD": "your_app_password"
+      }
+    }
+  }
+}
+```
+
+> [!TIP]
+> Generate an [app password](https://docs.nextcloud.com/server/latest/user_manual/en/session_management.html#managing-devices) in Nextcloud under **Settings > Security > Devices & sessions** instead of using your login password.
+
+### Docker
 
 For full features including semantic search, run with Docker:
 
@@ -35,9 +67,6 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
 curl http://127.0.0.1:8000/health/ready
 
 # 4. Connect to the endpoint
-http://127.0.0.1:8000/sse
-
-# Or with --transport streamable-http
 http://127.0.0.1:8000/mcp
 ```
 
@@ -56,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** - SSE, HTTP, and streamable-http support
+- **Multiple Transports** - streamable-http (default) and stdio
 
 ## Supported Apps
 
@@ -76,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!

nextcloud_mcp_server/app.py

@@ -119,17 +119,8 @@ from nextcloud_mcp_server.observability.metrics import (
     set_dependency_health,
 )
 from nextcloud_mcp_server.server import (
-    configure_calendar_tools,
-    configure_collectives_tools,
-    configure_contacts_tools,
-    configure_cookbook_tools,
-    configure_deck_tools,
-    configure_news_tools,
-    configure_notes_tools,
+    AVAILABLE_APPS,
     configure_semantic_tools,
-    configure_sharing_tools,
-    configure_tables_tools,
-    configure_webdav_tools,
 )
 from nextcloud_mcp_server.server.auth_tools import register_auth_tools
 from nextcloud_mcp_server.server.oauth_tools import register_oauth_tools
@@ -1232,32 +1223,18 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
         client = await get_nextcloud_client(ctx)
         return await client.capabilities()
 
-    # Define available apps and their configuration functions
-    available_apps = {
-        "notes": configure_notes_tools,
-        "tables": configure_tables_tools,
-        "webdav": configure_webdav_tools,
-        "sharing": configure_sharing_tools,
-        "calendar": configure_calendar_tools,
-        "collectives": configure_collectives_tools,
-        "contacts": configure_contacts_tools,
-        "cookbook": configure_cookbook_tools,
-        "deck": configure_deck_tools,
-        "news": configure_news_tools,
-    }
-
     # If no specific apps are specified, enable all
     if enabled_apps is None:
-        enabled_apps = list(available_apps.keys())
+        enabled_apps = list(AVAILABLE_APPS.keys())
 
     # Configure only the enabled apps
     for app_name in enabled_apps:
-        if app_name in available_apps:
+        if app_name in AVAILABLE_APPS:
             logger.info(f"Configuring {app_name} tools")
-            available_apps[app_name](mcp)
+            AVAILABLE_APPS[app_name](mcp)
         else:
             logger.warning(
-                f"Unknown app: {app_name}. Available apps: {list(available_apps.keys())}"
+                f"Unknown app: {app_name}. Available apps: {list(AVAILABLE_APPS.keys())}"
             )
 
     # Register semantic search tools (cross-app feature)

nextcloud_mcp_server/cli.py

@@ -14,6 +14,7 @@ from nextcloud_mcp_server.migrations import (
     upgrade_database,
 )
 from nextcloud_mcp_server.observability import get_uvicorn_logging_config
+from nextcloud_mcp_server.server import AVAILABLE_APPS
 
 from .app import get_app
 
@@ -38,16 +39,14 @@ from .app import get_app
     "-t",
     default="streamable-http",
     show_default=True,
-    type=click.Choice(["streamable-http", "http"]),
+    type=click.Choice(["streamable-http", "http", "stdio"]),
     help="MCP transport protocol",
 )
 @click.option(
     "--enable-app",
     "-e",
     multiple=True,
-    type=click.Choice(
-        ["notes", "tables", "webdav", "calendar", "contacts", "cookbook", "deck"]
-    ),
+    type=click.Choice(sorted(AVAILABLE_APPS.keys())),
     help="Enable specific Nextcloud app APIs. Can be specified multiple times. If not specified, all apps are enabled.",
 )
 @click.option(
@@ -158,6 +157,9 @@ def run(
       # OAuth with public issuer URL (for Docker/proxy setups)
       $ nextcloud-mcp-server --nextcloud-host=http://app --oauth \\
           --public-issuer-url=http://localhost:8080
+
+      # stdio transport for local use (e.g. Claude Code)
+      $ nextcloud-mcp-server run --transport stdio
     """
     # Set env vars from CLI options if provided
     if nextcloud_host:
@@ -241,6 +243,22 @@ def run(
 
     enabled_apps = list(enable_app) if enable_app else None
 
+    if transport == "stdio":
+        if oauth is True:
+            raise click.ClickException(
+                "stdio transport does not support OAuth mode. "
+                "Use single-user BasicAuth with NEXTCLOUD_HOST, "
+                "NEXTCLOUD_USERNAME, and NEXTCLOUD_PASSWORD."
+            )
+        from .stdio import get_stdio_mcp  # noqa: PLC0415
+
+        try:
+            mcp = get_stdio_mcp(enabled_apps=enabled_apps)
+        except ValueError as e:
+            raise click.ClickException(str(e)) from e
+        mcp.run(transport="stdio")
+        return
+
     app = get_app(transport=transport, enabled_apps=enabled_apps)
 
     # Get observability settings and create uvicorn logging config

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)

nextcloud_mcp_server/server/__init__.py

@@ -1,3 +1,7 @@
+from collections.abc import Callable
+
+from mcp.server.fastmcp import FastMCP
+
 from .calendar import configure_calendar_tools
 from .collectives import configure_collectives_tools
 from .contacts import configure_contacts_tools
@@ -10,7 +14,25 @@ from .sharing import configure_sharing_tools
 from .tables import configure_tables_tools
 from .webdav import configure_webdav_tools
 
+# Canonical mapping of app name → tool registration function.
+# Used by app.py (HTTP), stdio.py (stdio), and cli.py (--enable-app choices).
+# Semantic search is excluded here because it is a cross-app feature gated
+# by VECTOR_SYNC_ENABLED, not an individual Nextcloud app.
+AVAILABLE_APPS: dict[str, Callable[[FastMCP], None]] = {
+    "notes": configure_notes_tools,
+    "tables": configure_tables_tools,
+    "webdav": configure_webdav_tools,
+    "sharing": configure_sharing_tools,
+    "calendar": configure_calendar_tools,
+    "collectives": configure_collectives_tools,
+    "contacts": configure_contacts_tools,
+    "cookbook": configure_cookbook_tools,
+    "deck": configure_deck_tools,
+    "news": configure_news_tools,
+}
+
 __all__ = [
+    "AVAILABLE_APPS",
     "configure_calendar_tools",
     "configure_collectives_tools",
     "configure_contacts_tools",

nextcloud_mcp_server/stdio.py

@@ -0,0 +1,108 @@
+"""Lightweight stdio transport for the Nextcloud MCP server.
+
+Provides a minimal FastMCP instance suitable for ``mcp.run(transport="stdio")``.
+Only single-user BasicAuth mode is supported.  Background sync, semantic search,
+OAuth, and observability infrastructure are deliberately excluded.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+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
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StdioContext(BasicAuthLifespanContext):
+    """Minimal lifespan context for stdio transport.
+
+    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
+
+
+@asynccontextmanager
+async def stdio_lifespan(server: FastMCP) -> AsyncIterator[StdioContext]:
+    """Create and tear down a single :class:`NextcloudClient`."""
+    logger.info("Starting MCP server in stdio mode (single-user BasicAuth)")
+    client = NextcloudClient.from_env()
+    try:
+        yield StdioContext(client=client)
+    finally:
+        await client.close()
+        logger.info("stdio session shut down")
+
+
+def get_stdio_mcp(enabled_apps: list[str] | None = None) -> FastMCP:
+    """Return a :class:`FastMCP` instance configured for stdio transport.
+
+    Parameters
+    ----------
+    enabled_apps:
+        Whitelist of Nextcloud app names to register.  ``None`` means all.
+
+    Raises
+    ------
+    ValueError
+        If the current configuration is not single-user BasicAuth.
+    """
+    settings = get_settings()
+    mode, config_errors = validate_configuration(settings)
+
+    if config_errors:
+        raise ValueError(
+            f"Configuration validation failed for {mode.value} mode:\n"
+            + "\n".join(f"  - {err}" for err in config_errors)
+        )
+
+    if mode != AuthMode.SINGLE_USER_BASIC:
+        raise ValueError(
+            f"stdio transport only supports single-user BasicAuth mode, "
+            f"but detected {mode.value}. Set NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, "
+            f"and NEXTCLOUD_PASSWORD."
+        )
+
+    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"""
+        ctx: Context = mcp.get_context()
+        client = await get_nextcloud_client(ctx)
+        return await client.capabilities()
+
+    # --- tool registration ---
+    if enabled_apps is None:
+        enabled_apps = list(AVAILABLE_APPS.keys())
+
+    for app_name in enabled_apps:
+        if app_name in AVAILABLE_APPS:
+            logger.info("Configuring %s tools", app_name)
+            AVAILABLE_APPS[app_name](mcp)
+        else:
+            logger.warning(
+                "Unknown app: %s. Available apps: %s",
+                app_name,
+                list(AVAILABLE_APPS.keys()),
+            )
+
+    return mcp

tests/test_cli.py

@@ -285,3 +285,42 @@ def test_oauth_token_type_case_normalization(runner, clean_env, monkeypatch):
     captured_env.clear()
     runner.invoke(run, ["--oauth-token-type", "Bearer"])
     assert captured_env["NEXTCLOUD_OIDC_TOKEN_TYPE"] in ["Bearer", "bearer"]
+
+
+def test_help_includes_stdio_transport(runner):
+    """Test that stdio appears as a transport option in help output."""
+    result = runner.invoke(run, ["--help"])
+    assert result.exit_code == 0
+    assert "stdio" in result.output
+
+
+def test_stdio_rejects_oauth_flag(runner, clean_env, monkeypatch):
+    """Test that --transport stdio --oauth raises an error."""
+    monkeypatch.setenv("NEXTCLOUD_HOST", "https://cloud.example.com")
+    result = runner.invoke(run, ["--transport", "stdio", "--oauth"])
+    assert result.exit_code != 0
+    assert "stdio transport does not support OAuth mode" in result.output
+
+
+def test_stdio_calls_get_stdio_mcp(runner, clean_env, monkeypatch):
+    """Test that --transport stdio invokes the stdio code path."""
+    monkeypatch.setenv("NEXTCLOUD_HOST", "https://cloud.example.com")
+    monkeypatch.setenv("NEXTCLOUD_USERNAME", "admin")
+    monkeypatch.setenv("NEXTCLOUD_PASSWORD", "secret")
+
+    called_with = {}
+
+    class FakeMcp:
+        def run(self, transport):
+            called_with["transport"] = transport
+
+    def mock_get_stdio_mcp(enabled_apps=None):
+        called_with["enabled_apps"] = enabled_apps
+        return FakeMcp()
+
+    monkeypatch.setattr("nextcloud_mcp_server.stdio.get_stdio_mcp", mock_get_stdio_mcp)
+
+    result = runner.invoke(run, ["--transport", "stdio"])
+    assert result.exit_code == 0, result.output
+    assert called_with.get("transport") == "stdio"
+    assert called_with.get("enabled_apps") is None

tests/unit/test_stdio.py

@@ -0,0 +1,106 @@
+"""Unit tests for the stdio transport module."""
+
+import pytest
+from mcp.server.fastmcp import FastMCP
+
+from nextcloud_mcp_server.config import _reload_config
+from nextcloud_mcp_server.config_validators import AuthMode
+from nextcloud_mcp_server.stdio import get_stdio_mcp
+
+
+@pytest.fixture
+def single_user_env(monkeypatch):
+    """Set up environment variables for single-user BasicAuth mode."""
+    monkeypatch.setenv("NEXTCLOUD_HOST", "https://cloud.example.com")
+    monkeypatch.setenv("NEXTCLOUD_USERNAME", "admin")
+    monkeypatch.setenv("NEXTCLOUD_PASSWORD", "secret")
+    # Ensure multi-user mode is off (may leak from other tests)
+    monkeypatch.delenv("ENABLE_MULTI_USER_BASIC_AUTH", raising=False)
+    _reload_config()
+    yield
+    _reload_config()
+
+
+@pytest.mark.unit
+def test_get_stdio_mcp_returns_fastmcp(single_user_env):
+    """get_stdio_mcp returns a FastMCP instance with correct env vars."""
+    mcp = get_stdio_mcp()
+    assert isinstance(mcp, FastMCP)
+
+
+@pytest.mark.unit
+def test_get_stdio_mcp_rejects_config_errors(monkeypatch):
+    """get_stdio_mcp raises ValueError when validate_configuration reports errors."""
+    monkeypatch.setattr(
+        "nextcloud_mcp_server.stdio.validate_configuration",
+        lambda _settings: (AuthMode.SINGLE_USER_BASIC, ["missing nextcloud_host"]),
+    )
+    with pytest.raises(ValueError, match="Configuration validation failed"):
+        get_stdio_mcp()
+
+
+@pytest.mark.unit
+def test_get_stdio_mcp_rejects_non_single_user_mode(monkeypatch):
+    """get_stdio_mcp raises ValueError for non-single-user modes."""
+    monkeypatch.setattr(
+        "nextcloud_mcp_server.stdio.validate_configuration",
+        lambda _settings: (AuthMode.MULTI_USER_BASIC, []),
+    )
+    with pytest.raises(ValueError, match="single-user BasicAuth"):
+        get_stdio_mcp()
+
+
+@pytest.mark.unit
+def test_get_stdio_mcp_registers_all_apps_by_default(single_user_env):
+    """All app tool groups are registered when no filter is specified."""
+    mcp = get_stdio_mcp()
+    # NOTE: _tool_manager is a FastMCP internal; may break on SDK upgrades
+    tools = mcp._tool_manager.list_tools()
+    tool_names = {t.name for t in tools}
+
+    # Spot-check representative tools from each app
+    assert "nc_notes_get_note" in tool_names
+    assert "nc_webdav_list_directory" in tool_names
+    assert "nc_calendar_list_calendars" in tool_names
+    assert "nc_contacts_list_addressbooks" in tool_names
+    assert "nc_cookbook_list_recipes" in tool_names
+    assert "deck_get_boards" in tool_names
+    assert "nc_tables_list_tables" in tool_names
+    assert "nc_share_list" in tool_names
+    assert "nc_news_list_feeds" in tool_names
+    assert "collectives_get_collectives" in tool_names
+
+
+@pytest.mark.unit
+def test_get_stdio_mcp_respects_enabled_apps(single_user_env):
+    """Only specified apps have their tools registered."""
+    mcp = get_stdio_mcp(enabled_apps=["notes"])
+    # NOTE: _tool_manager is a FastMCP internal; may break on SDK upgrades
+    tools = mcp._tool_manager.list_tools()
+    tool_names = {t.name for t in tools}
+
+    assert "nc_notes_get_note" in tool_names
+    # Other apps should NOT be present
+    assert "nc_webdav_list_directory" not in tool_names
+    assert "nc_calendar_list_calendars" not in tool_names
+
+
+@pytest.mark.unit
+def test_get_stdio_mcp_no_semantic_tools(single_user_env):
+    """Semantic search tools are never registered in stdio mode."""
+    mcp = get_stdio_mcp()
+    # NOTE: _tool_manager is a FastMCP internal; may break on SDK upgrades
+    tools = mcp._tool_manager.list_tools()
+    tool_names = {t.name for t in tools}
+
+    semantic_names = [n for n in tool_names if "semantic" in n or "vector" in n]
+    assert semantic_names == [], f"Unexpected semantic tools: {semantic_names}"
+
+
+@pytest.mark.unit
+def test_get_stdio_mcp_registers_capabilities_resource(single_user_env):
+    """The nc://capabilities resource is registered."""
+    mcp = get_stdio_mcp()
+    # NOTE: _resource_manager._resources is a FastMCP internal; may break on SDK upgrades
+    resources = mcp._resource_manager._resources
+    assert "nc://capabilities" in resources