You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs(client): ClientSession documents only the input-required kwargs, not its mandatory parameters #3846
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.
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:
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.
I wrote the patch for this: #3848 (closed by require-linked-issue because I am not assigned here — it reopens on its own if a maintainer assigns this issue). The branch is lxcxjxhx:docs/session-args, one commit, 14 lines added, docstrings only.
name, arguments, read_timeout_seconds, progress_callback, meta
get_prompt
name, arguments, meta
On the overload question from the earlier comment: mkdocs.yml sets no show_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 @overload stubs would be four copies of the same text.
Verification: AST comparison against the previous head is identical with docstrings excluded; parsing the module with ast shows every parameter of the four methods now appears in its Args: block; pytest tests/client/test_session.py → 94 passed; ruff check and ruff format --check pass.
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.
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.