[mcp] fix: classify list_gpus enumeration unavailability

[Wangmerlyn]

Summary

• Classify expected DeviceEnumerationUnavailableError from direct JSON-RPC list_gpus as startup-unavailable (-32000) instead of internal error.
• Return MCP tools/call list_gpus enumeration failures as tool errors (result.isError=true) while preserving malformed listing payloads as internal contract errors.
• Update MCP docs, AGENTS guidance, and the implementation plan. README remains compact and the Zenodo DOI badge is preserved.

Local review

• Local subagent review found no Critical, Important, or Minor issues.
• Reviewer confirmed malformed list_gpus records remain internal errors and unexpected MCP tool failures still return JSON-RPC -32603.

Verification

• RED before fix: new targeted tests failed with direct JSON-RPC -32603 and MCP top-level protocol error.
• PYTHONPATH=$PWD/src pytest tests/mcp/test_server.py::test_jsonrpc_list_gpus_device_enumeration_unavailable_returns_public_code tests/mcp/test_server.py::test_mcp_tools_call_list_gpus_device_enumeration_unavailable_returns_tool_error -q: 2 passed.
• PYTHONPATH=$PWD/src pytest tests/mcp/test_server.py -q -k 'list_gpus or startup_unavailable or tools_call': 26 passed, 109 deselected.
• PYTHONPATH=$PWD/src pytest tests/mcp tests/utilities/test_gpu_info.py -q: 300 passed, 1 skipped.
• PYTHONPATH=$PWD/src pytest -q: 845 passed, 11 skipped.
• PYTHONPATH=$PWD/src mkdocs build --strict: passed with the existing Material for MkDocs upstream warning.
• pre-commit run --all-files --show-diff-on-failure: passed.
• git diff --check: passed.

Summary by CodeRabbit

• Bug Fixes

  • GPU listing failures now return a consistent startup-unavailable response across JSON-RPC, MCP tool calls, and the API.
  • Malformed GPU listing responses are treated as internal service errors rather than startup-unavailable failures.

• Documentation

  • Clarified which GPU enumeration failures map to startup-unavailable behavior.
  • Added guidance for the expected responses from GPU listing operations.

• Tests

  • Added coverage for GPU enumeration failure handling in both JSON-RPC and MCP tool call flows.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f6b5a887-ccd1-471a-a89c-4a15e01ffa6c

📥 Commits

Reviewing files that changed from the base of the PR and between 93b5e59 and e9567e8.

📒 Files selected for processing (5)

• AGENTS.md
• docs/guides/mcp.md
• docs/plans/mcp-list-gpus-unavailable.md
• src/keep_gpu/mcp/server.py
• tests/mcp/test_server.py

---

📝 Walkthrough

Walkthrough

This PR maps DeviceEnumerationUnavailableError to the startup-unavailable JSON-RPC error code in the MCP server's _call_keepgpu_method, adds regression tests for both direct JSON-RPC and MCP tools/call list_gpus paths, and updates documentation (AGENTS.md, mcp guide) plus a new planning document.

Changes

MCP list_gpus startup-unavailable classification

Layer / File(s)	Summary
Server error mapping src/keep_gpu/mcp/server.py	_call_keepgpu_method catches DeviceEnumerationUnavailableError alongside SessionStartupUnavailable, mapping both to JSONRPC_STARTUP_UNAVAILABLE.
Regression tests tests/mcp/test_server.py	New tests verify JSON-RPC list_gpus returns the public startup-unavailable error, and MCP tools/call list_gpus returns result.isError=true when get_gpu_info raises DeviceEnumerationUnavailableError.
Documentation and plan AGENTS.md, docs/guides/mcp.md, docs/plans/mcp-list-gpus-unavailable.md	Guidance and docs are updated to describe list_gpus enumeration failures as startup-unavailable, and a new plan document records the inconsistency and proposed fix.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant MCPServer as MCP Server (_call_keepgpu_method)
  participant GPUInfo as get_gpu_info

  Client->>MCPServer: list_gpus request (JSON-RPC or tools/call)
  MCPServer->>GPUInfo: get_gpu_info()
  GPUInfo-->>MCPServer: raise DeviceEnumerationUnavailableError
  alt Direct JSON-RPC
    MCPServer-->>Client: error code JSONRPC_STARTUP_UNAVAILABLE
  else MCP tools/call
    MCPServer-->>Client: result.isError=true, startup-unavailable message
  end

Loading

Possibly related PRs

• Wangmerlyn/KeepGPU#59: Introduced MCP server list_gpus support that this PR's error-handling extends.
• Wangmerlyn/KeepGPU#137: Modifies the same MCP server error-mapping logic for startup-unavailable vs internal-error envelopes.
• Wangmerlyn/KeepGPU#151: Directly changes handling of DeviceEnumerationUnavailableError in the same JSON-RPC/MCP surfaces.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately reflects the main MCP change: classifying list_gpus enumeration failures as unavailable.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/mcp-list-gpus-unavailable

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}