Repository navigation
docs(client): ClientSession documents only the input-required kwargs, not its mandatory parameters #3846
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
Reproduced on main (77001c9), and the drift is wider than the four methods listed.
read_resource at src/mcp/client/session.py:933 documents input_responses, request_state and allow_input_required, and omits uri and meta, exactly as reported. uri is the only parameter without a default, so the rendered page shows the three optional kwargs and hides the one argument a caller has to pass.
Two additions:
send_request at line 540 documents only metadata, and omits request, result_type, request_read_timeout_seconds and progress_callback. request is mandatory there as well, so the same loss happens on the method every other call funnels through.
The two read_resource overloads above the real definition, lines 912 and 923, carry no Args block at all. If the docs render the overloads rather than the implementation, none of the parameters are documented, so it is worth confirming which signature mkdocstrings picks before writing the blocks. Otherwise the fix can land on a signature the reference never shows.
On the cause: the Args block is rendered verbatim, so a missing parameter is silently missing rather than defaulting to anything. Completing the blocks fixes today; a test that walks the public client methods and asserts every parameter name appears in its Args section would fix the class, and would have caught the four methods here plus the three neighbours copied from the same block.
Happy to open the PR with the completed blocks if that is useful, including the overload question answered first.
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.