fix(stremio_mcp): guard ANDROID_TV_PORT parsing with bounded _env_int

[netixc]

Intent

Validate and ship the committed ANDROID_TV_PORT startup guard for stremio-mcp before the 0.2.0 release path. The defect was an unguarded import-time int(os.getenv("ANDROID_TV_PORT", "5555")) that crashed the entire MCP server on empty, quoted, nonnumeric, or otherwise invalid values, and accepted out-of-range ports.

Captain-approved scope (already committed on this branch; do not expand):

• Replace that one-off parse with the existing _env_int helper: ANDROID_TV_PORT = _env_int("ANDROID_TV_PORT", 5555, 1, 65535).
• Invalid/empty values must not crash import/startup; fall back to default 5555 and emit only the existing safe configuration warning shape (variable name only; never log or return the raw configured value).
• Preserve valid custom ports including boundaries 1 and 65535, and all other configuration/runtime behavior.
• Focused subprocess regression tests for absent, empty, whitespace/quoted, nonnumeric, negative/zero, above-range, valid custom, and boundary values.
• Genuine fail-before (7 failures on defective parse) / pass-after (10 OK) evidence captured; full suite 132 tests OK. Preserve that evidence and the one-change scope.
• Unreleased changelog Fixed entry only. Do NOT bump package/server/README versions, cut a release, tag, publish, or change release metadata.
• No real TV, credentials, network, ADB, or device mutation. Do not alter native ADB, MCP v1, playback, or unrelated audit items.
• Target netixc/stremio-mcp only.

What Changed

• Replaced the unguarded import-time int(os.getenv("ANDROID_TV_PORT", "5555")) parse with _env_int("ANDROID_TV_PORT", 5555, 1, 65535), so empty, quoted, whitespace, non-numeric, or out-of-range values fall back to the default 5555 instead of crashing MCP server startup, while valid custom ports (including boundaries 1 and 65535) are preserved.
• Added focused subprocess regression tests covering absent, empty, whitespace/quoted, non-numeric, negative/zero, above-range, valid custom, and boundary port values, confirming invalid inputs fall back safely and never leak the raw configured value into the warning.
• Recorded the fix under the unreleased Fixed section of CHANGELOG.md with no version bump or release metadata changes.

Risk Assessment

✅ Low: A single, well-bounded one-line fix replacing an unguarded int parse with the existing validated _env_int helper, backed by focused subprocess regression tests and an unreleased-only changelog entry, all matching the authoritative intent.

Testing

Baseline locked setup, the 10 focused subprocess regression tests, and the full 132-test suite all pass. I then demonstrated the actual end-user surface by importing the server module across every ANDROID_TV_PORT value category: the fixed code survives import (exit 0) for all invalid/out-of-range values, falls back to 5555, and warns with the variable name only — confirmed the raw secret value never appears in a warning — while valid custom (37139) and boundary ports (1, 65535) pass through unchanged. A before/after contrast confirms the old unguarded parse crashed with ValueError on empty/whitespace/quoted/nonnumeric input and silently accepted 0/70000, matching the reported defect. Worktree left clean.

Evidence: Fixed server import behavior across all ANDROID_TV_PORT values

absent/empty -> 5555 (exit 0, no warn); whitespace/quoted/abc -> 5555 + 'is not an integer' warn (exit 0); -1/0/70000 -> 5555 + 'is outside 1-65535' warn (exit 0); 37139 -> 37139; 1 -> 1; 65535 -> 65535. Raw value 37139 never appears in any warning line.

### Fixed stremio-mcp startup across ANDROID_TV_PORT values (exit 0 = server import survives; secret 37139 must never appear in a warning)

=== absent (unset) ===
ANDROID_TV_PORT = 5555
exit code: 0

=== empty string ===
ANDROID_TV_PORT = 5555
exit code: 0

=== whitespace '   ' ===
WARNING:stremio-mcp:ANDROID_TV_PORT is not an integer; using the default.
ANDROID_TV_PORT = 5555
exit code: 0

=== quoted '"37139"' ===
WARNING:stremio-mcp:ANDROID_TV_PORT is not an integer; using the default.
ANDROID_TV_PORT = 5555
exit code: 0

=== nonnumeric 'abc' ===
WARNING:stremio-mcp:ANDROID_TV_PORT is not an integer; using the default.
ANDROID_TV_PORT = 5555
exit code: 0

=== negative '-1' ===
WARNING:stremio-mcp:ANDROID_TV_PORT is outside 1-65535; using the default.
ANDROID_TV_PORT = 5555
exit code: 0

=== zero '0' ===
WARNING:stremio-mcp:ANDROID_TV_PORT is outside 1-65535; using the default.
ANDROID_TV_PORT = 5555
exit code: 0

=== above-range '70000' ===
WARNING:stremio-mcp:ANDROID_TV_PORT is outside 1-65535; using the default.
ANDROID_TV_PORT = 5555
exit code: 0

=== valid custom '37139' ===
ANDROID_TV_PORT = 37139
exit code: 0

=== boundary '1' ===
ANDROID_TV_PORT = 1
exit code: 0

=== boundary '65535' ===
ANDROID_TV_PORT = 65535
exit code: 0

Evidence: Before-fix defect: old int(os.getenv(...)) parse crashed / accepted out-of-range

empty/' '/'"37139"'/abc -> ValueError: invalid literal for int() (exit 1, import crash); 0 -> 0 and 70000 -> 70000 (exit 0, out-of-range silently accepted).

### BEFORE fix: import-time int(os.getenv("ANDROID_TV_PORT","5555")) crashed the server on invalid values

=== ANDROID_TV_PORT='' (empty) (old unguarded int(os.getenv(...)) parse) ===
Traceback (most recent call last):
ValueError: invalid literal for int() with base 10: ''
exit code: 1

=== ANDROID_TV_PORT='   ' (old unguarded int(os.getenv(...)) parse) ===
Traceback (most recent call last):
ValueError: invalid literal for int() with base 10: '   '
exit code: 1

=== ANDROID_TV_PORT='"37139"' (old unguarded int(os.getenv(...)) parse) ===
Traceback (most recent call last):
ValueError: invalid literal for int() with base 10: '"37139"'
exit code: 1

=== ANDROID_TV_PORT='abc' (old unguarded int(os.getenv(...)) parse) ===
Traceback (most recent call last):
ValueError: invalid literal for int() with base 10: 'abc'
exit code: 1

=== ANDROID_TV_PORT='0' (out-of-range accepted!) (old unguarded int(os.getenv(...)) parse) ===
ANDROID_TV_PORT = 0
ANDROID_TV_PORT = 0
exit code: 0

=== ANDROID_TV_PORT='70000' (out-of-range accepted!) (old unguarded int(os.getenv(...)) parse) ===
ANDROID_TV_PORT = 70000
ANDROID_TV_PORT = 70000
exit code: 0

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• uv sync --locked (locked setup)
• uv run --locked python -m unittest tests.test_stremio_mcp.AndroidTvPortConfigTests -v — 10 focused subprocess tests OK
• uv run --locked python -m unittest discover -s tests — full suite 132 tests OK
• Manual end-user import probe: imported stremio_mcp with ANDROID_TV_PORT set to absent/empty/whitespace/quoted/nonnumeric/-1/0/70000/37139/1/65535, recording exit code, resulting port, and warning text
• Before/after contrast: ran the old unguarded int(os.getenv('ANDROID_TV_PORT','5555')) parse to reproduce the ValueError crash and out-of-range acceptance
• Verified via grep that the raw configured value 37139 never leaks into any fallback warning

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.