[mcp] fix: return jsonrpc parse error envelopes

[Wangmerlyn]

Summary

• Return JSON-RPC -32700 Parse error envelopes for malformed HTTP JSON-RPC bodies on / and /rpc.
• Keep REST /api/sessions malformed-body errors as structured HTTP 400 responses.
• Document the protocol boundary in AGENTS, the MCP guide, and a focused plan doc.

Test Plan

• RED before implementation: PYTHONPATH=$PWD/src pytest tests/mcp/test_http_api.py::test_http_jsonrpc_parse_error_returns_jsonrpc_envelope -q failed because /rpc returned HTTP 400.
• PYTHONPATH=$PWD/src pytest tests/mcp/test_http_api.py::test_http_jsonrpc_parse_error_returns_jsonrpc_envelope -q -> 2 passed for / and /rpc.
• PYTHONPATH=$PWD/src pytest tests/mcp/test_http_api.py -q -> 51 passed.
• PYTHONPATH=$PWD/src pytest tests/mcp -q -> 142 passed.
• PYTHONPATH=$PWD/src pytest tests -q -> 474 passed, 11 skipped.
• pre-commit run --all-files -> passed.
• PYTHONPATH=$PWD/src mkdocs build -> passed with existing MkDocs/material and unnav warnings.
• git diff --check origin/main..HEAD -> passed.

Local Review

• Spec compliance subagent: approved; no missing requirements or extra behavior.
• Code quality subagent: no Critical or Important issues. Minor docstring/MCP-guide polish was addressed before PR.

Summary by CodeRabbit

• Bug Fixes

  • HTTP JSON-RPC endpoints now return a proper JSON-RPC parse-error response for malformed request bodies, including the expected error code and id: null.
  • REST endpoints continue to return structured REST-style JSON errors for invalid input.

• Documentation

  • Updated the HTTP JSON-RPC guidance to reflect the revised error behavior.
  • Added implementation notes and verification guidance for the new parsing behavior.

[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: f4c3f64e-bcd8-4673-8403-b798d5c3c1f0

📥 Commits

Reviewing files that changed from the base of the PR and between b4a86c2 and 260b1b8.

📒 Files selected for processing (5)

• AGENTS.md
• docs/guides/mcp.md
• docs/plans/http-jsonrpc-parse-error-envelope.md
• src/keep_gpu/mcp/server.py
• tests/mcp/test_http_api.py

---

📝 Walkthrough

Walkthrough

do_POST in KeepGPUServer now returns a JSON-RPC -32700 parse-error envelope (HTTP 200) for malformed bodies on / and /rpc, while REST endpoints keep HTTP 400. A parametrized test covers both paths, and AGENTS.md, docs/guides/mcp.md, and a new plan file document this behavior.

Changes

JSON-RPC Parse Error Envelope

Layer / File(s)	Summary
Server parse error handling and test src/keep_gpu/mcp/server.py, tests/mcp/test_http_api.py	do_POST branches on path: / and /rpc parse failures call _jsonrpc_error(None, JSONRPC_PARSE_ERROR, ...) and respond HTTP 200; other paths keep HTTP 400. New parametrized test sends b"{" to both paths and asserts HTTP 200 with a JSON-RPC 2.0 envelope, id: None, and code -32700.
Documentation and guidelines AGENTS.md, docs/guides/mcp.md, docs/plans/http-jsonrpc-parse-error-envelope.md	AGENTS.md adds an explicit rule for JSON-RPC envelope errors on / and /rpc; mcp.md documents the -32700 envelope with id: null; the plan file lists implementation tasks and expected test outcomes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• Wangmerlyn/KeepGPU#60: Adds the HTTP JSON-RPC POST handler for / and /rpc in do_POST, which this PR modifies for parse-error handling.
• Wangmerlyn/KeepGPU#96: Refactors REST JSON error responses in do_POST, directly adjacent to the parse-error branching logic changed here.

Poem

🐇 A curly brace left open wide,
Once caused a 400 to hide,
Now /rpc replies with grace—
A JSON-RPC error in its place,
id: null, code -32700 inside! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: returning JSON-RPC parse error envelopes for malformed requests.
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/http-jsonrpc-parse-error-envelope

---

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.}

[gemini-code-assist]

Code Review

This pull request updates the HTTP POST handler to return standard JSON-RPC parse error envelopes (with error code -32700 and HTTP status 200) for malformed requests sent to the / and /rpc endpoints, while keeping REST-shaped HTTP 400 errors for other routes. The changes include updates to documentation (AGENTS.md, docs/guides/mcp.md), a new implementation plan, and a parameterized test to verify the new behavior. There are no review comments, and I have no additional feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.