insightfactory-cli 1.1.2.dev30__tar.gz → 1.1.2.dev31__tar.gz

{insightfactory_cli-1.1.2.dev30 → insightfactory_cli-1.1.2.dev31}/CHANGELOG.md

@@ -31,6 +31,12 @@ last one has been released, so a cycle's PRs share a section.
 
 ### Changed
 
+- The router's stderr lines now carry the elapsed time since startup, and it logs when
+  the catalogue build starts and when it answers its first `initialize`, so an operator
+  can tell a slow process apart from a slow factory and a client that called before the
+  handshake finished. `if-cli mcp` also now logs a `starting on Python <version>` line
+  before doing anything else, so a process that dies during argument parsing, config
+  load, or profile lookup still leaves one line on stderr instead of none.
 - `release-guard` asks every PR into `develop` for a `CHANGELOG.md` entry, and asks
   for a version bump only when `develop` is still on the version `main` is on. One
   bump opens a release cycle and the PRs after it add to the section it opened,

{insightfactory_cli-1.1.2.dev30 → insightfactory_cli-1.1.2.dev31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: insightfactory-cli
-Version: 1.1.2.dev30
+Version: 1.1.2.dev31
 Summary: Profile-based authentication CLI for the InsightFactory Interfaces API
 Project-URL: Homepage, https://insightfactory.ai
 Author-email: "insightfactory.ai Support" <support@insightfactory.ai>
@@ -265,6 +265,14 @@ uv tool install 'insightfactory-cli[mcp]'
 uvx --from 'insightfactory-cli[mcp]' if-cli mcp foundry
 ```
 
+The first `uvx` launch resolves and downloads the package from PyPI before it runs, which
+added roughly four to six seconds on top of the usual startup in local testing, against
+under two seconds once `uv`'s cache was warm. A client with a fixed handshake budget
+(Claude Code allows 30 seconds) usually has room for that, but a slow network can close
+the gap. Two ways to avoid paying it on every launch: `uv tool install 'insightfactory-cli[mcp]'`
+puts a real script on `PATH` with no resolve step, or run the same `uvx --from ...` command
+by hand once before pointing a client at it, which warms `uv`'s cache for the launches after.
+
 Add it to `.mcp.json`:
 
 ```json

{insightfactory_cli-1.1.2.dev30 → insightfactory_cli-1.1.2.dev31}/README.md

@@ -241,6 +241,14 @@ uv tool install 'insightfactory-cli[mcp]'
 uvx --from 'insightfactory-cli[mcp]' if-cli mcp foundry
 ```
 
+The first `uvx` launch resolves and downloads the package from PyPI before it runs, which
+added roughly four to six seconds on top of the usual startup in local testing, against
+under two seconds once `uv`'s cache was warm. A client with a fixed handshake budget
+(Claude Code allows 30 seconds) usually has room for that, but a slow network can close
+the gap. Two ways to avoid paying it on every launch: `uv tool install 'insightfactory-cli[mcp]'`
+puts a real script on `PATH` with no resolve step, or run the same `uvx --from ...` command
+by hand once before pointing a client at it, which warms `uv`'s cache for the launches after.
+
 Add it to `.mcp.json`:
 
 ```json

{insightfactory_cli-1.1.2.dev30 → insightfactory_cli-1.1.2.dev31}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "insightfactory-cli"
-version = "1.1.2.dev30"
+version = "1.1.2.dev31"
 description = "Profile-based authentication CLI for the InsightFactory Interfaces API"
 readme = "README.md"
 requires-python = ">=3.10"

{insightfactory_cli-1.1.2.dev30 → insightfactory_cli-1.1.2.dev31}/src/if_cli/commands/mcp.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 import importlib.util
+import platform
 import sys
 
 from if_cli.cli import Options, parse_args
 from if_cli.config import config_file, get_profile, list_factories, load_config, parse_factory_section
 from if_cli.http import parse_timeout_seconds
+from if_cli.router.log import log
 from if_cli.runtime import die
 
 MCP_OPTIONS: Options = {
@@ -75,6 +77,8 @@ def _stray_positional(rest: list[str]) -> str | None:
 
 
 def mcp_command(argv: list[str]) -> None:
+    log(f"starting on Python {platform.python_version()}")
+
     if "-h" in argv or "--help" in argv:
         sys.stdout.write(MCP_USAGE)
         return
@@ -146,7 +150,6 @@ def mcp_command(argv: list[str]) -> None:
     # import bug inside if_cli.router propagates instead of reading as a missing extra.
     if importlib.util.find_spec("mcp") is None:
         die(MISSING_MCP_EXTRA)
-    from if_cli.router.log import log
     from if_cli.router.server import build_router, run_server
 
     timeout = parse_timeout_seconds(values["timeout"], "--timeout")

insightfactory_cli-1.1.2.dev31/src/if_cli/router/log.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import sys
+import time
+
+# Captured at import: this module loads before the router does anything else
+# diagnosable, so it stands in for process start. Two `log()` lines can then
+# be subtracted to time the phase between them.
+_START = time.monotonic()
+
+
+def log(message: str) -> None:
+    """Write one timestamped diagnostic line to stderr.
+
+    The router speaks MCP over stdout, so stderr is the only channel that can
+    carry anything to the operator. This lives in its own module because both
+    `server` and `upstream` write to it and `server` imports `upstream`.
+    """
+    elapsed_ms = round((time.monotonic() - _START) * 1000)
+    sys.stderr.write(f"[if-cli mcp] +{elapsed_ms}ms {message}\n")

{insightfactory_cli-1.1.2.dev30 → insightfactory_cli-1.1.2.dev31}/src/if_cli/router/server.py

@@ -9,7 +9,7 @@ from typing import Any, TypeVar
 import anyio
 import mcp_types as types
 from mcp.server import Server
-from mcp.server.context import ServerRequestContext
+from mcp.server.context import CallNext, HandlerResult, ServerMiddleware, ServerRequestContext
 from mcp.server.stdio import stdio_server
 from mcp.shared.exceptions import MCPError
 
@@ -137,6 +137,7 @@ class Router:
 
     async def build_catalog(self) -> list[types.Tool]:
         """Build the merged catalogue. Safe to call again to pick up a new login."""
+        log(f"catalogue: building from {self.config.catalog_source}")
         catalogues = await self._catalogues()
         source = catalogues.get(self.config.catalog_source)
         if source is None:
@@ -536,6 +537,27 @@ def advertised_extensions(router: Router) -> dict[str, dict[str, Any]]:
     return {SKILLS_EXTENSION: {}} if router.config.skills else {}
 
 
+def _log_first_initialize() -> ServerMiddleware[Any]:
+    """Log once the router has answered a client's `initialize`.
+
+    Read against `prime_catalog`'s startup log lines, this tells an operator
+    apart a slow process (nothing logged yet), a slow factory (catalogue
+    build still running past this point), and a client that called before
+    the handshake (a tool call logged before this line ever appears).
+    """
+    logged = False
+
+    async def middleware(ctx: ServerRequestContext[Any, Any], call_next: CallNext) -> HandlerResult:
+        nonlocal logged
+        result = await call_next(ctx)
+        if not logged and ctx.method == "initialize":
+            logged = True
+            log("answered the first initialize")
+        return result
+
+    return middleware
+
+
 async def _serve(router: Router) -> None:
     server: Server[Any] = Server(
         SERVER_NAME,
@@ -553,6 +575,7 @@ async def _serve(router: Router) -> None:
     # the handshake rebuilds its capabilities from `server.extensions` once the
     # protocol version is known, and ignores the ones computed here.
     server.extensions = advertised_extensions(router)
+    server.middleware.append(_log_first_initialize())
     # Answer `initialize` immediately: the catalogue build runs as a background
     # task so one hung factory reads as a slow tools/list, not a failed
     # handshake (clients cap startup time).

{insightfactory_cli-1.1.2.dev30 → insightfactory_cli-1.1.2.dev31}/tests/test_mcp_command.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import subprocess
 import sys
 import time
@@ -802,11 +803,10 @@ def test_mcp_command_logs_the_resolved_factory_mapping_at_startup(tmp_path: Path
 
         anyio.run(scenario)
         stderr_text = stderr_path.read_text(encoding="utf-8")
-        expected = (
-            f"[if-cli mcp] foundry: dev=profile-a {server_a.origin} (writable); "
-            f"tst=profile-b {server_b.origin}; catalog=dev"
+        expected = re.escape(
+            f"foundry: dev=profile-a {server_a.origin} (writable); tst=profile-b {server_b.origin}; catalog=dev"
         )
-        assert expected in stderr_text
+        assert re.search(rf"\[if-cli mcp\] \+\d+ms {expected}", stderr_text)
     finally:
         server_a.close()
         server_b.close()
@@ -827,8 +827,8 @@ def test_mcp_command_logs_environments_label_without_a_factory(tmp_path: Path):
 
         anyio.run(scenario)
         stderr_text = stderr_path.read_text(encoding="utf-8")
-        expected = f"[if-cli mcp] environments: a=profile-a {server.origin} (writable); catalog=a"
-        assert expected in stderr_text
+        expected = re.escape(f"environments: a=profile-a {server.origin} (writable); catalog=a")
+        assert re.search(rf"\[if-cli mcp\] \+\d+ms {expected}", stderr_text)
     finally:
         server.close()
 

insightfactory_cli-1.1.2.dev31/tests/test_router_log.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from if_cli.router import log as log_module
+
+
+def test_log_prefixes_the_elapsed_time_since_process_start(monkeypatch, capsys):
+    monkeypatch.setattr(log_module, "_START", 10.0)
+    monkeypatch.setattr(log_module.time, "monotonic", lambda: 10.25)
+
+    log_module.log("ready over stdio")
+
+    assert capsys.readouterr().err == "[if-cli mcp] +250ms ready over stdio\n"
+
+
+def test_log_keeps_the_grep_prefix_first(monkeypatch, capsys):
+    """`[if-cli mcp]` must stay the first thing on the line, timestamp or not:
+    it is what an operator (or a script) greps a stdio transcript for."""
+    monkeypatch.setattr(log_module, "_START", 0.0)
+    monkeypatch.setattr(log_module.time, "monotonic", lambda: 0.0)
+
+    log_module.log("WARN dropped a connect URL")
+
+    assert capsys.readouterr().err.startswith("[if-cli mcp] +0ms ")

{insightfactory_cli-1.1.2.dev30 → insightfactory_cli-1.1.2.dev31}/tests/test_router_upstream.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+import re
 from typing import Any
 
 import pytest
@@ -373,7 +374,9 @@ def test_a_dropped_connect_url_is_reported_on_stderr(capsys):
     anyio.run(lambda: upstream.call_tool("run_sql_query", {}))
 
     stderr = capsys.readouterr().err
-    assert "[if-cli mcp] WARN dropped a connect URL that is not on https://factory.example" in stderr
+    assert re.search(
+        r"\[if-cli mcp\] \+\d+ms WARN dropped a connect URL that is not on https://factory\.example", stderr
+    )
     assert "https://phish.example/connect" in stderr
 
 

insightfactory_cli-1.1.2.dev30/src/if_cli/router/log.py

@@ -1,13 +0,0 @@
-from __future__ import annotations
-
-import sys
-
-
-def log(message: str) -> None:
-    """Write one diagnostic line to stderr.
-
-    The router speaks MCP over stdout, so stderr is the only channel that can
-    carry anything to the operator. This lives in its own module because both
-    `server` and `upstream` write to it and `server` imports `upstream`.
-    """
-    sys.stderr.write(f"[if-cli mcp] {message}\n")