chore: clean CodeQL baseline findings

Author: ayhammouda

src/mcp_server_python_docs/__main__.py

@@ -27,6 +27,7 @@ def _close_saved_stdout_fd() -> None:
     try:
         os.close(_saved_stdout_fd)
     except OSError:
+        # Best-effort cleanup; the fd may already be closed during interpreter shutdown.
         pass
     finally:
         _saved_stdout_fd = None
@@ -515,6 +516,7 @@ def doctor() -> None:
             test_file.unlink()
             cache_writable = True
         except OSError:
+            # Doctor reports the cache as not writable below.
             pass
     cache_ok = True  # Not existing yet is OK (will be created on first build)
     cache_detail = str(cache_dir)

src/mcp_server_python_docs/detection.py

@@ -44,6 +44,7 @@ def detect_python_version() -> tuple[str, str]:
                 logger.info("Detected Python %s from .python-version", version)
                 return version, ".python-version file"
         except Exception:
+            # The version file is optional; fall through to active interpreter probing.
             pass
 
     # 2. python3 --version in PATH
@@ -60,6 +61,7 @@ def detect_python_version() -> tuple[str, str]:
                 logger.info("Detected Python %s from python3 in PATH", version)
                 return version, "python3 in PATH"
     except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        # python3 may be absent or too slow; fall through to the server runtime.
         pass
 
     # 3. Server's own runtime

src/mcp_server_python_docs/ingestion/sphinx_json.py

@@ -508,6 +508,7 @@ def ingest_fjson_file(
         try:
             conn.rollback()
         except Exception:
+            # Keep reporting the original ingestion failure if rollback also fails.
             pass
         return False
 

src/mcp_server_python_docs/server.py

@@ -197,13 +197,15 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
                 error_log = cache_dir / "last-error.log"
                 error_log.write_text(error_msg)
             except Exception:
+                # Best-effort diagnostic write; preserve the original lifespan error.
                 pass
             raise
     finally:
         if persistent_docs_cache is not None:
             try:
                 persistent_docs_cache.close()
             except Exception:
+                # Best-effort cleanup during shutdown.
                 pass
         db.close()
 

src/mcp_server_python_docs/services/package_docs.py

@@ -34,9 +34,14 @@
 
 
 class _HTTPResponse(Protocol):
-    def read(self, size: int = -1) -> bytes: ...
-    def __enter__(self) -> "_HTTPResponse": ...
-    def __exit__(self, exc_type: object, exc: object, tb: object) -> bool | None: ...
+    def read(self, size: int = -1) -> bytes:
+        raise NotImplementedError
+
+    def __enter__(self) -> "_HTTPResponse":
+        raise NotImplementedError
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> bool | None:
+        raise NotImplementedError
 
 
 Fetcher = Callable[[str, float], _HTTPResponse]

tests/test_package_docs.py

@@ -59,10 +59,8 @@ def fetch(url: str, timeout: float):
             "project_urls": {"Community mirror": "https://mirror.example/demo"}}})
 
     result = PackageDocsService(fetcher=fetch).lookup("demo")
-    urls = [s.url for s in result.sources]
-    assert "https://demo.example/" in urls
-    assert "https://random-blog.example/demo" not in urls
-    assert "https://mirror.example/demo" not in urls
+    urls = {s.url for s in result.sources}
+    assert urls == {"https://pypi.org/project/demo/", "https://demo.example/"}
     assert "community mirror" in (result.note or "").lower()
 
 

tests/test_stdio_smoke.py

@@ -250,6 +250,7 @@ def read_stream(stream, sink: list[bytes]) -> None:
             try:
                 proc.stdin.close()
             except BrokenPipeError:
+                # The subprocess may have already closed stdin after handling the requests.
                 pass
             proc.stdin = None