fix: report MCP server import failures in doctor

Merged
BO
1mo ago
+1901-13

agy-doctor now imports the installed agy_mcp.server and registers its tools in a fresh interpreter. Import failures make the report unhealthy with a bounded, redacted exception type and message. Import output is discarded; the five-second import timeout kills and reaps the direct child and removes its diagnostic directory. The check leaves server state uninitialized and requires no network access or authentication. Fixes #14.

The probe preserves the entrypoint search order, effective interpreter modes, parsed startup warning options, integer conversion limit, and current bytecode cache settings. Its child-only environment copy removes stale overrides for the settings replayed on the command line, including late user-site and safe-path overrides. An already-present PYTHONHOME is reconstructed from the caller's base installation when environment settings are enabled, preserving tested venv and alternate-home layouts. Other variables, including fresh PYTHONPATH overrides, remain available. This does not clone raw environment keys, arbitrary later sys.path additions, or runtime warning filters.

The MCP doctor tool runs blocking checks in an AnyIO worker so status and cancellation remain responsive during a hanging import. State and adapter selection remain on the event loop. An instance lock shares each adapter's cold capability probe while preserving cache retry and refresh behavior. Dependency-created descendants remain outside the direct-child cleanup guarantee.

Validation on this candidate: 94 affected tests passed on Linux/Python 3.12, including the seven targeted search/environment cases. Twelve separate public first-import cases passed in owned installations: eight on Python 3.12 and four HOME/layout cases on Python 3.14.6. Ruff, an offline wheel/sdist build, and the artifact audit passed. These local checks are selected regressions; local full-suite and native Windows runs were not performed.

CI for 6b29d59 passed all five code jobs and 48 steps, including the required lint/test/build/artifact checks and Linux/macOS compatibility tests on Python 3.11 and 3.13: CI run.

Summary by Sourcery

Make agy-doctor detect MCP server import and registration failures safely without blocking the MCP event loop or mutating server state.

New Features:

  • Add an agy-doctor check that validates fresh MCP server imports and tool registration in the active Python environment, reporting redacted diagnostics and unhealthy status on failure.

Bug Fixes:

  • Prevent concurrent capability detection from running duplicate probes and allow retries after a failed probe.
  • Keep doctor probes isolated from server initialization while preserving the caller's Python startup, import, dependency, and warning behavior.

Enhancements:

  • Run the asynchronous doctor tool's blocking diagnostics in a worker thread so other MCP calls remain responsive.
  • Add bounded, quiet, timeout-protected probe execution with validation and cleanup of diagnostic results.

Tests:

  • Add focused coverage for server import and tool-registration failures, redaction, timeout cleanup, interpreter flags, entrypoint behavior, dependency precedence, state isolation, and concurrent doctor calls.

Summary by CodeRabbit

  • Bug Fixes
    • The doctor check now verifies that the MCP server can start and reports import, startup, timeout, and diagnostic errors as failed checks, with sensitive details redacted.
    • Doctor checks no longer block other MCP activity while in progress, and failures are reported without exposing credentials.
    • Concurrent capability checks now share a consistent result, and failed checks can be retried.