diff --git a/Dockerfile b/Dockerfile index 39b16066..90264468 100644 --- a/Dockerfile +++ b/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"] diff --git a/README.md b/README.md index 1cab6035..601aced4 100644 --- a/README.md +++ b/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 diff --git a/nextcloud_mcp_server/cli.py b/nextcloud_mcp_server/cli.py index 4fcf8612..645453cc 100644 --- a/nextcloud_mcp_server/cli.py +++ b/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 diff --git a/nextcloud_mcp_server/stdio.py b/nextcloud_mcp_server/stdio.py new file mode 100644 index 00000000..b4952b90 --- /dev/null +++ b/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 diff --git a/tests/test_cli.py b/tests/test_cli.py index 0481955f..40570c31 100644 --- a/tests/test_cli.py +++ b/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 diff --git a/tests/unit/test_stdio.py b/tests/unit/test_stdio.py new file mode 100644 index 00000000..371a3139 --- /dev/null +++ b/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