fix: improve binary install experience by beonde · Pull Request #8 · capiscio/capiscio-mcp-python

beonde · 2026-03-11T19:28:22Z

Summary

Fixes binary install experience issues identified in the install audit. Companion to capiscio/capiscio-sdk-python#38.

P0 Fixes

Visible download output: First-run binary download now writes to stderr so users see progress even without logging configured
Version mismatch: CORE_MIN_VERSION updated from 2.3.0 to 2.4.0 to match SDK
Error message: Health check error now uses CORE_MIN_VERSION/CORE_MAX_VERSION constants instead of hardcoded 2.5.0

P1 Fixes

Shared cache directory: Changed from platformdirs.user_cache_dir("capiscio-mcp") to ~/.capiscio/bin/ so SDK and MCP share the same binary cache
Removed platformdirs dependency: No longer needed after cache dir change
Retry with backoff: Download retries 3 times with exponential backoff (1s, 2s) before failing

Files Changed

capiscio_mcp/_core/lifecycle.py — Download visibility, shared cache, retry logic
capiscio_mcp/_core/version.py — Version bump
capiscio_mcp/_core/health.py — Dynamic error message
pyproject.toml — Remove platformdirs dep

Testing

All 350 unit tests passing

- Add visible stderr output during binary download (P0) - Fix CORE_MIN_VERSION 2.3.0 -> 2.4.0 to match SDK (P0) - Fix hardcoded version string in health check error message (P0) - Align cache directory to ~/.capiscio/bin/ (shared with SDK) (P1) - Remove unused platformdirs dependency (P1) - Add retry with exponential backoff for download (3 attempts) (P1)

github-actions · 2026-03-11T19:29:39Z

✅ Integration tests passed! capiscio-core gRPC tests working.

Copilot

Pull request overview

Updates capiscio-core compatibility requirements and binary lifecycle behavior to align with the current MCP SDK expectations, while simplifying cache-path handling and dependency set.

Changes:

Removed platformdirs dependency and switched binary cache location to ~/.capiscio/bin.
Raised CORE_MIN_VERSION to 2.4.0 and updated version compatibility messaging to use constants.
Added retry/backoff logic and user-facing stderr output during binary download/install.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
`pyproject.toml`	Drops `platformdirs` dependency after cache-dir implementation change.
`capiscio_mcp/_core/version.py`	Raises minimum compatible `capiscio-core` version to `2.4.0`.
`capiscio_mcp/_core/lifecycle.py`	Changes cache dir path and adds download retry/backoff plus stderr output.
`capiscio_mcp/_core/health.py`	Uses version constants in the incompatibility error message (and expands imports).

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-11T19:32:22Z

capiscio_mcp/_core/lifecycle.py

+    sys.stderr.write(
+        f"capiscio-core v{version} not found. "
+        f"Downloading for {os_name}/{arch_name}...\n"
+    )
+    sys.stderr.flush()


Avoid writing directly to sys.stderr from this library function. It produces unconfigurable output for SDK consumers (including tests/host apps). Prefer logger output (or gate the message behind an explicit verbose/debug flag).

Copilot · 2026-03-11T19:32:22Z

capiscio_mcp/_core/lifecycle.py

+    max_attempts = 3
+    for attempt in range(1, max_attempts + 1):
+        try:
+            response = requests.get(url, stream=True, timeout=60)
+            response.raise_for_status()
+
+            # Write binary
+            with open(target_path, "wb") as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    f.write(chunk)
+
+            # Make executable (Unix)
+            if os_name != "windows":
+                st = os.stat(target_path)
+                os.chmod(target_path, st.st_mode | stat.S_IEXEC)
+
+            sys.stderr.write(f"Installed capiscio-core v{version} at {target_path}\n")
+            sys.stderr.flush()
+            logger.info(f"Successfully installed capiscio-core v{version}")
+            return target_path
+
+        except Exception as e:
+            if target_path.exists():
+                target_path.unlink()
+            if attempt < max_attempts:
+                delay = 2 ** (attempt - 1)
+                logger.warning(
+                    f"Download attempt {attempt}/{max_attempts} failed: {e}. "
+                    f"Retrying in {delay}s..."
+                )
+                time.sleep(delay)
+            else:


This retry loop will also retry (and sleep) on permanent failures like HTTP 404/400 from raise_for_status(), which adds avoidable startup latency and slows the existing unit test that mocks a 404. Consider retrying only on transient errors (timeouts/connection errors/5xx), and fail fast on 4xx.

Copilot · 2026-03-11T19:32:22Z

capiscio_mcp/_core/lifecycle.py

+            response = requests.get(url, stream=True, timeout=60)
+            response.raise_for_status()
+
+            # Write binary
+            with open(target_path, "wb") as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    f.write(chunk)
+


The streaming download doesn't explicitly close the HTTP response. Using a context manager (or calling response.close()) helps avoid leaking connections across retries and keeps the requests connection pool healthy.

Suggested change

response = requests.get(url, stream=True, timeout=60)

response.raise_for_status()

# Write binary

with open(target_path, "wb") as f:

for chunk in response.iter_content(chunk_size=8192):

f.write(chunk)

with requests.get(url, stream=True, timeout=60) as response:

response.raise_for_status()

# Write binary

with open(target_path, "wb") as f:

for chunk in response.iter_content(chunk_size=8192):

f.write(chunk)

Copilot · 2026-03-11T19:32:22Z

capiscio_mcp/_core/lifecycle.py

+            sys.stderr.write(f"Installed capiscio-core v{version} at {target_path}\n")
+            sys.stderr.flush()
+            logger.info(f"Successfully installed capiscio-core v{version}")


Avoid writing directly to sys.stderr on successful install as well; this is noisy for library consumers. Prefer logging (or an opt-in progress callback/flag) so callers can control where output goes.

Copilot · 2026-03-11T19:32:23Z

capiscio_mcp/_core/health.py

 from typing import TYPE_CHECKING

-from capiscio_mcp._core.version import is_core_compatible, PROTO_VERSION
+from capiscio_mcp._core.version import is_core_compatible, PROTO_VERSION, CORE_MIN_VERSION, CORE_MAX_VERSION


This import line exceeds the configured 100-char line length and will be reformatted by Black. Please wrap it using parentheses to keep formatting consistent with the repo's Black configuration.

Suggested change

from capiscio_mcp._core.version import is_core_compatible, PROTO_VERSION, CORE_MIN_VERSION, CORE_MAX_VERSION

from capiscio_mcp._core.version import (

is_core_compatible,

PROTO_VERSION,

CORE_MIN_VERSION,

CORE_MAX_VERSION,

)

- Replace sys.stderr.write with logger.info for download messages - Use requests.get as context manager to prevent connection leaks - Only retry on transient errors (5xx/timeout/connection); fail fast on 4xx - Wrap long import line in health.py for Black compliance - Remove unused sys import - Update 404 test mock for context manager + fast-fail behavior

github-actions · 2026-03-11T20:20:37Z

✅ Integration tests passed! capiscio-core gRPC tests working.

Copilot AI review requested due to automatic review settings March 11, 2026 19:28

Copilot started reviewing on behalf of beonde March 11, 2026 19:29 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

beonde merged commit c2f69fd into main Mar 11, 2026
10 checks passed

beonde deleted the fix/binary-install-experience branch March 11, 2026 20:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: improve binary install experience#8

fix: improve binary install experience#8
beonde merged 2 commits intomainfrom
fix/binary-install-experience

beonde commented Mar 11, 2026

Uh oh!

github-actions bot commented Mar 11, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

github-actions bot commented Mar 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

beonde commented Mar 11, 2026

Summary

P0 Fixes

P1 Fixes

Files Changed

Testing

Uh oh!

github-actions bot commented Mar 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants