Repository navigation
Description
What is wrong
ClientSession.read_resource (src/mcp/client/session.py, docstring at 933) has a Google-style Args: block that lists only the three optional input-required kwargs:
documented in Args: ['input_responses', 'request_state', 'allow_input_required']
real parameters : ['uri', 'input_responses', 'request_state', 'meta', 'allow_input_required']
UNDOCUMENTED : ['uri', 'meta']
uri is the only parameter without a default, so the rendered API reference documents the optional arguments and hides the mandatory one. meta is undocumented as well.
The higher-level Client.read_resource (src/mcp/client/client.py:662,666) documents both correctly, so this looks like drift confined to the session layer rather than an intentional omission.
Minimal reproduction
import inspect
from mcp.client.session import ClientSession
print(inspect.signature(ClientSession.read_resource))
# (uri: AnyUrl, input_responses: ... = None, request_state: ... = None,
# meta: ... = None, allow_input_required: bool = False) -> ReadResourceResultScope of the drift
The same pattern appears on three neighbouring methods in the same class, measured the same way on main — every one of them documents the input-required kwargs and nothing else, which suggests the block was written once and copied:
| Method | Documented in Args: |
Actually accepted |
|---|---|---|
send_request (l. 540) |
metadata |
request, result_type, request_read_timeout_seconds, metadata, progress_callback |
call_tool (l. 1052) |
input_responses, request_state, allow_input_required, allow_claimed |
name, arguments, read_timeout_seconds, progress_callback, input_responses, request_state, meta, allow_input_required, allow_claimed |
get_prompt (l. 1217) |
input_responses, request_state, allow_input_required |
name, arguments, input_responses, request_state, meta, allow_input_required |
call_tool is the most visible case: name and arguments are the two parameters every caller passes and neither is documented.
Proposed fix
Add the undocumented parameters to each Args: block, reusing the wording already used in the Client layer where the same parameter appears. Docstring-only, one file, no behaviour change; ruff check and ruff format --check pass on the file.
I am proposing this as one issue, because the four blocks share a cause and the fix is one file. Say the word if you would rather take read_resource alone and file the rest separately, and I will split it.
Willing to open a PR?
Yes — assign this to me (or label it help wanted) and I'll send it. I've read the intake gate and will include Fixes #<this> plus the AI-assistance disclosure the contributing guide asks for.
Activity
media-ctrl commentedon Nov 10, 2026
lxcxjxhx commentedon Nov 11, 2026
I wrote the patch for this: #3848 (closed by
require-linked-issuebecause I am not assigned here — it reopens on its own if a maintainer assigns this issue). The branch islxcxjxhx:docs/session-args, one commit, 14 lines added, docstrings only.What it does, in case it saves someone the pass:
send_requestrequest,result_type,request_read_timeout_seconds,progress_callbackread_resourceuri,metacall_toolname,arguments,read_timeout_seconds,progress_callback,metaget_promptname,arguments,metaOn the overload question from the earlier comment:
mkdocs.ymlsets noshow_overloads, so mkdocstrings renders the overload signatures and takes the docstring from the implementation — the blocks belong on the implementation, and duplicating them onto the four@overloadstubs would be four copies of the same text.Verification: AST comparison against the previous head is identical with docstrings excluded; parsing the module with
astshows every parameter of the four methods now appears in itsArgs:block;pytest tests/client/test_session.py→ 94 passed;ruff checkandruff format --checkpass.I did not add the walk-the-methods test that was suggested — that is a test-suite change and I would rather keep this to the docstrings unless you want both in one place.