feat: add stdio transport support for local MCP usage

Add a lightweight stdio transport path so users can run the server
locally with MCP clients like Claude Code using `uvx nextcloud-mcp-server run`.

- New `nextcloud_mcp_server/stdio.py` with minimal FastMCP setup for
  single-user BasicAuth (no OAuth, semantic search, or background sync)
- Default transport changed from streamable-http to stdio
- Dockerfile updated to explicitly use streamable-http for containers
- CLI `--enable-app` now includes news, collectives, and sharing
- README Quick Start section with uvx and MCP client config examples

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Dockerfile

@@ -27,4 +27,4 @@ ENV VIRTUAL_ENV=/app/.venv
 ENV PATH=/app/.venv/bin:$PATH
 ENV TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata
 
-ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "run", "--host", "0.0.0.0"]
+ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "run", "--transport", "streamable-http", "--host", "0.0.0.0"]

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
+```
+
+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"],
+      "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
 ```
 
@@ -62,7 +91,7 @@ docker compose --profile login-flow up -d         # Port 8004
 - **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** - stdio (default) and streamable-http
 
 ## Supported Apps
 

nextcloud_mcp_server/cli.py

@@ -36,9 +36,9 @@ from .app import get_app
 @click.option(
     "--transport",
     "-t",
-    default="streamable-http",
+    default="stdio",
     show_default=True,
-    type=click.Choice(["streamable-http", "http"]),
+    type=click.Choice(["stdio", "streamable-http", "http"]),
     help="MCP transport protocol",
 )
 @click.option(
@@ -46,7 +46,18 @@ from .app import get_app
     "-e",
     multiple=True,
     type=click.Choice(
-        ["notes", "tables", "webdav", "calendar", "contacts", "cookbook", "deck"]
+        [
+            "notes",
+            "tables",
+            "webdav",
+            "calendar",
+            "contacts",
+            "cookbook",
+            "deck",
+            "news",
+            "collectives",
+            "sharing",
+        ]
     ),
     help="Enable specific Nextcloud app APIs. Can be specified multiple times. If not specified, all apps are enabled.",
 )
@@ -158,6 +169,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 +255,19 @@ 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
+
+        mcp = get_stdio_mcp(enabled_apps=enabled_apps)
+        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/stdio.py

@@ -0,0 +1,128 @@
+"""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 typing import Callable
+
+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 get_client as get_nextcloud_client
+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,
+    configure_sharing_tools,
+    configure_tables_tools,
+    configure_webdav_tools,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class StdioContext:
+    """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`.
+    """
+
+    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) ---
+    @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 ---
+    available_apps: dict[str, Callable] = {
+        "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 enabled_apps is None:
+        enabled_apps = list(available_apps.keys())
+
+    for app_name in enabled_apps:
+        if app_name in available_apps:
+            logger.info(f"Configuring {app_name} tools")
+            available_apps[app_name](mcp)
+        else:
+            logger.warning(
+                f"Unknown app: {app_name}. "
+                f"Available apps: {list(available_apps.keys())}"
+            )
+
+    return mcp

tests/test_cli.py

@@ -108,6 +108,8 @@ def test_cli_options_set_environment_variables(runner, clean_env, monkeypatch):
     _ = runner.invoke(
         run,
         [
+            "--transport",
+            "streamable-http",
             "--nextcloud-host",
             "https://test.example.com",
             "--nextcloud-username",
@@ -164,6 +166,8 @@ def test_cli_options_override_environment_variables(runner, monkeypatch):
     _ = runner.invoke(
         run,
         [
+            "--transport",
+            "streamable-http",
             "--nextcloud-host",
             "https://from-cli.example.com",
             "--nextcloud-username",
@@ -214,7 +218,7 @@ def test_environment_variables_used_when_cli_not_provided(runner, monkeypatch):
     monkeypatch.setattr("nextcloud_mcp_server.cli.get_app", mock_get_app)
 
     # Don't provide any CLI options - should use env vars
-    _ = runner.invoke(run, [])
+    _ = runner.invoke(run, ["--transport", "streamable-http"])
 
     # Verify env vars were used
     assert captured_env["NEXTCLOUD_HOST"] == "https://from-env.example.com"
@@ -246,7 +250,7 @@ def test_default_values(runner, clean_env, monkeypatch):
     monkeypatch.setattr("nextcloud_mcp_server.cli.get_app", mock_get_app)
 
     # Don't provide CLI options or env vars - should use defaults
-    _ = runner.invoke(run, [])
+    _ = runner.invoke(run, ["--transport", "streamable-http"])
 
     # Verify default values
     assert captured_env["NEXTCLOUD_OIDC_SCOPES"] == (
@@ -278,10 +282,55 @@ def test_oauth_token_type_case_normalization(runner, clean_env, monkeypatch):
     monkeypatch.setattr("nextcloud_mcp_server.cli.get_app", mock_get_app)
 
     # Test uppercase JWT
-    runner.invoke(run, ["--oauth-token-type", "JWT"])
+    runner.invoke(run, ["--transport", "streamable-http", "--oauth-token-type", "JWT"])
     assert captured_env["NEXTCLOUD_OIDC_TOKEN_TYPE"] in ["JWT", "jwt"]
 
     # Test mixed case Bearer
     captured_env.clear()
-    runner.invoke(run, ["--oauth-token-type", "Bearer"])
+    runner.invoke(
+        run, ["--transport", "streamable-http", "--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.cli.get_stdio_mcp", mock_get_stdio_mcp, raising=False
+    )
+    # The lazy import means we need to patch at the module level it imports from
+    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,96 @@
+"""Unit tests for the stdio transport module."""
+
+import pytest
+from mcp.server.fastmcp import FastMCP
+
+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")
+
+
+@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()
+    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"])
+    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()
+    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()
+    resources = mcp._resource_manager._resources
+    assert "nc://capabilities" in resources