feat(mcp): report config sources only when OSW_VERBOSE is set

- add Settings.verbose, read from OSW_VERBOSE or OSW_MCP_VERBOSE
- MCP server buffers the credential and env-file lines instead of
  writing them to stderr at every start
- a failed start still prints both lines, verbose or not
- CLI output is unchanged

Author: LukasGold

docs/cli-and-mcp.md

@@ -271,9 +271,15 @@ and `credentials` when none was:
 - `OSW_USERNAME/OSW_PASSWORD (from the env file)`
 - `not configured (set OSW_CRED_FILEPATH, or OSW_USERNAME/OSW_PASSWORD)`
 
-The second line is labelled `env file`. The MCP server prints both lines. The
-CLI prints the first only, adding the second with `--verbose` or when the
-command fails:
+The second line is labelled `env file`. Which lines appear depends on the
+adapter:
+
+- **CLI**: the first line only. `--verbose`, or a command that fails, adds
+  the second.
+- **MCP server**: neither, since its sources are fixed in the server entry.
+  `OSW_VERBOSE=true` prints both, and a failed start prints both regardless.
+
+A verbose run prints:
 
 ```text
 [osw] credential file: /home/me/project/accounts.pwd.yaml (accounts.pwd.yaml found in the working directory)
@@ -287,7 +293,7 @@ process only, and never written back to disk. Set either `OSW_USERNAME` and
 `OSW_PASSWORD`, or `OSW_CRED_FILEPATH`.
 
 A credential file uses the YAML format osw's `CredentialManager` reads, keyed
-by iri:
+by iri (default file name: `accounts.pwd.yaml`):
 
 ```yaml
 wiki-dev.open-semantic-lab.org:
@@ -317,6 +323,7 @@ set wins:
 | `OSW_STATE_DIR` | `OSW_MCP_STATE_DIR` | Where the provenance ledger is kept |
 | `OSW_MAX_RESULTS` | `OSW_MCP_MAX_RESULTS` | Default result cap (100) |
 | `OSW_MAX_CHARS` | `OSW_MCP_MAX_CHARS` | Result size cap in characters (100000) |
+| `OSW_VERBOSE` | `OSW_MCP_VERBOSE` | `true` prints the configuration source report |
 
 ### Windows paths in a `.env` file
 

src/osw/mcp/server.py

@@ -9,8 +9,9 @@
 
 import atexit
 import inspect
+import io
 import sys
-from typing import Any, Optional
+from typing import Any, Optional, TextIO
 
 from mcp.server import MCPServer
 from mcp.types import ToolAnnotations
@@ -95,7 +96,7 @@ def tool_kwargs(op: Operation, settings: Settings) -> dict[str, Any]:
     }
 
 
-def _build_server() -> tuple[MCPServer, Context]:
+def _build_server(report: Optional[TextIO] = None) -> tuple[MCPServer, Context]:
     """Build the MCPServer and the Context its tools are bound to.
 
     Loads and validates settings first so a missing-credential misconfiguration
@@ -106,11 +107,16 @@ def _build_server() -> tuple[MCPServer, Context]:
     Deliberately stricter than :func:`config.get_active_domain`, which the CLI
     uses: there the instance is resolved per invocation and reported at
     startup, and ``--instance`` can override it per command.
+
+    ``report`` receives the configuration source lines instead of stderr, so
+    the caller decides whether to show them. With no ``report`` they are
+    discarded.
     """
     # Before get_settings(), so a misconfiguration that makes loading raise
-    # still reports which files were read. stderr, so it lands in the MCP
-    # client's server log without touching the JSON-RPC stream on stdout.
-    config.log_config_sources()
+    # still reports which files were read. Into `report` rather than stderr:
+    # these lines repeat the client's own server entry, so main() shows them
+    # only when asked or when the start fails.
+    config.log_config_sources(stream=report if report is not None else io.StringIO())
     settings = config.get_settings()
     domain = settings.domain
     if domain is None:
@@ -145,12 +151,20 @@ def create_server() -> MCPServer:
 
 def main() -> None:
     """Console-script entry point: build the server and serve over stdio."""
+    report = io.StringIO()
     try:
-        mcp, ctx = _build_server()
+        mcp, ctx = _build_server(report)
     except Exception as exc:
-        print(f"[osw-mcp] failed to start: {exc}", file=sys.stderr)
+        # A failed start is when the configuration sources matter most, so
+        # they are printed even with OSW_VERBOSE unset.
+        sys.stderr.write(report.getvalue())
+        print(f"[osw-mcp] failed to start: {exc}", file=sys.stderr, flush=True)
         raise SystemExit(1) from exc
 
+    if config.get_settings().verbose:
+        sys.stderr.write(report.getvalue())
+        sys.stderr.flush()
+
     atexit.register(ctx.close)
     try:
         mcp.run(transport="stdio")

src/osw/service/config.py

@@ -39,6 +39,7 @@
 ENV_MAX_RESULTS = ("OSW_MAX_RESULTS", "OSW_MCP_MAX_RESULTS")
 ENV_MAX_CHARS = ("OSW_MAX_CHARS", "OSW_MCP_MAX_CHARS")
 ENV_FILE = ("OSW_ENV_FILE", "OSW_MCP_ENV_FILE")
+ENV_VERBOSE = ("OSW_VERBOSE", "OSW_MCP_VERBOSE")
 
 
 def _first_env(names: tuple[str, ...]) -> Optional[str]:
@@ -62,6 +63,7 @@ def _first_env(names: tuple[str, ...]) -> Optional[str]:
     "state_dir": ENV_STATE_DIR,
     "max_results": ENV_MAX_RESULTS,
     "max_chars": ENV_MAX_CHARS,
+    "verbose": ENV_VERBOSE,
 }
 
 
@@ -100,6 +102,9 @@ class Settings(BaseModel):
     state_dir: Optional[str] = None
     max_results: int = Field(default=100, gt=0)
     max_chars: int = Field(default=100_000, gt=0)
+    # Only controls the startup configuration report. No tool or command
+    # reads it, and Settings.redacted() deliberately does not expose it.
+    verbose: bool = False
 
     @field_validator("domain")
     @classmethod
@@ -440,14 +445,16 @@ def log_config_sources(stream=None, verbose: bool = True) -> None:
     the CLI's failure path, which prints the env-file line (via
     :func:`log_env_file_source`) after this one has already run.
 
-    ``verbose`` defaults to ``True``, which keeps both lines and matches the
-    MCP server's behaviour (it never passes a value here). The CLI passes
+    ``verbose`` defaults to ``True``, which keeps both lines. The CLI passes
     ``verbose=False`` for a successful, non-verbose command, and prints the
     env-file line separately (via :func:`log_env_file_source`) on failure or
-    when the user passed ``--verbose``.
+    when the user passed ``--verbose``. The MCP server writes both lines to a
+    buffer instead of stderr and shows them only when ``OSW_VERBOSE`` is set
+    or the server fails to start.
 
-    Always writes to ``stderr``: under MCP ``stdout`` carries the JSON-RPC
-    stream, and under ``osw --json`` it carries the result payload.
+    Writes to ``stderr``, or to ``stream`` when one is given, and never to
+    ``stdout``: under MCP ``stdout`` carries the JSON-RPC stream, and under
+    ``osw --json`` it carries the result payload.
     """
     _load_env_file()
     # Every print below flushes: stderr is block-buffered whenever it is not a
@@ -638,6 +645,9 @@ def load(strict: bool = True) -> Settings:
     max_chars_raw = _first_env(ENV_MAX_CHARS)
     if max_chars_raw is not None and max_chars_raw.strip():
         kwargs["max_chars"] = max_chars_raw
+    verbose_raw = _first_env(ENV_VERBOSE)
+    if verbose_raw is not None and verbose_raw.strip():
+        kwargs["verbose"] = verbose_raw
 
     try:
         return Settings(**kwargs)

tests/test_cli.py

@@ -45,6 +45,8 @@
     "OSW_MCP_MAX_CHARS",
     "OSW_ENV_FILE",
     "OSW_MCP_ENV_FILE",
+    "OSW_VERBOSE",
+    "OSW_MCP_VERBOSE",
 ]
 
 

tests/test_mcp_server.py

@@ -10,6 +10,7 @@
 from __future__ import annotations
 
 import asyncio
+import io
 
 import pytest
 import yaml
@@ -31,6 +32,8 @@
     "OSW_READ_ONLY",
     "OSW_MCP_READ_ONLY",
     "OSW_MCP_ENV_FILE",
+    "OSW_VERBOSE",
+    "OSW_MCP_VERBOSE",
 ]
 
 
@@ -156,3 +159,39 @@ def test_create_server_does_not_auto_select_a_single_iri(monkeypatch, tmp_path):
 
     with pytest.raises(RuntimeError, match="No OSL instance configured"):
         server.create_server()
+
+
+def test_build_server_is_quiet_by_default(monkeypatch, capsys):
+    # The configuration source lines repeat what the MCP client's server entry
+    # already says, so a successful start says nothing without OSW_VERBOSE.
+    _configure(monkeypatch)
+
+    server.create_server()
+
+    assert "[osw]" not in capsys.readouterr().err
+
+
+def test_build_server_writes_the_report_into_the_given_buffer(monkeypatch, capsys):
+    _configure(monkeypatch)
+    buf = io.StringIO()
+
+    _mcp, ctx = server._build_server(buf)
+    ctx.close()
+
+    assert "[osw] credentials" in buf.getvalue()
+    assert capsys.readouterr().err == ""
+
+
+def test_main_prints_the_report_when_startup_fails(monkeypatch, tmp_path, capsys):
+    # No OSW_DOMAIN: _build_server raises, and that is exactly when the
+    # configuration sources have to be visible, OSW_VERBOSE or not.
+    cred_file = _write_cred_file(tmp_path, ["wiki-a.example.org", "wiki-b.example.org"])
+    monkeypatch.setenv("OSW_MCP_CRED_FILEPATH", str(cred_file))
+    config.reset()
+
+    with pytest.raises(SystemExit):
+        server.main()
+
+    err = capsys.readouterr().err
+    assert "[osw] " in err
+    assert "failed to start" in err

tests/test_service_config.py

@@ -31,6 +31,8 @@
     "OSW_MCP_MAX_CHARS",
     "OSW_ENV_FILE",
     "OSW_MCP_ENV_FILE",
+    "OSW_VERBOSE",
+    "OSW_MCP_VERBOSE",
 ]
 
 
@@ -1012,6 +1014,26 @@ def test_blank_read_only_falls_back_to_default(monkeypatch):
     assert config.load().read_only is False
 
 
+def test_verbose_defaults_to_false_and_is_set_by_the_env_variable(monkeypatch):
+    monkeypatch.setenv("OSW_DOMAIN", "wiki.example.org")
+    monkeypatch.setenv("OSW_USERNAME", "alice")
+    monkeypatch.setenv("OSW_PASSWORD", "secret")
+    assert config.load().verbose is False
+
+    monkeypatch.setenv("OSW_VERBOSE", "true")
+    assert config.load().verbose is True
+
+
+def test_misspelled_verbose_raises(monkeypatch):
+    monkeypatch.setenv("OSW_DOMAIN", "wiki.example.org")
+    monkeypatch.setenv("OSW_USERNAME", "alice")
+    monkeypatch.setenv("OSW_PASSWORD", "secret")
+    monkeypatch.setenv("OSW_VERBOSE", "ture")
+    with pytest.raises(RuntimeError) as exc:
+        config.load()
+    assert "OSW_VERBOSE" in str(exc.value)
+
+
 def test_read_only_error_names_the_alias_that_was_set(monkeypatch):
     monkeypatch.setenv("OSW_DOMAIN", "wiki.example.org")
     monkeypatch.setenv("OSW_USERNAME", "alice")

tests/test_service_instances.py

@@ -28,6 +28,8 @@
     "OSW_MCP_MAX_CHARS",
     "OSW_ENV_FILE",
     "OSW_MCP_ENV_FILE",
+    "OSW_VERBOSE",
+    "OSW_MCP_VERBOSE",
 ]