Add resolver dependency injection for MCPServer tools by Kludex · Pull Request #2969 · modelcontextprotocol/python-sdk

Kludex · 2026-06-25T13:45:13Z

Summary

Adds server-side dependency injection for @mcp.tool() functions. A tool parameter annotated Annotated[T, Resolve(fn)] is filled by running the resolver fn before the tool body, instead of by the calling LLM. Resolvers form a dependency graph: a resolver may declare its own Resolve(...) dependencies, read the Context (including the new Context.headers), and receive the tool's own arguments by name. A resolver may return Elicit[T] to ask the client; the SDK runs the elicitation and injects the answer. Each resolver runs at most once per tools/call.

from typing import Annotated

from pydantic import BaseModel

from mcp.server.mcpserver import Context, Elicit, MCPServer, Resolve

mcp = MCPServer(name="github")


class Login(BaseModel):
    username: str


class Confirm(BaseModel):
    ok: bool


async def login(ctx: Context) -> Login | Elicit[Login]:
    if username := (ctx.headers or {}).get("x-github-user"):
        return Login(username=username)        # resolved from context, no question
    return Elicit("GitHub username?", Login)    # must ask


async def confirm(repo: str, login: Annotated[Login, Resolve(login)]) -> Elicit[Confirm]:
    return Elicit(f"Star {repo} as {login.username}?", Confirm)


@mcp.tool()
async def star_repo(
    repo: str,
    login: Annotated[Login, Resolve(login)],
    confirm: Annotated[Confirm, Resolve(confirm)],
) -> str:
    """Star a GitHub repo."""
    return f"starred {repo} as {login.username}" if confirm.ok else "cancelled"

Design

Mechanism reuses the existing Context-injection seam: resolvers are detected at registration (Tool.from_function), excluded from the tool's JSON input schema via skip_names, and supplied at call time through arguments_to_pass_directly - so they bypass argument validation exactly like Context does today.
Headers come from the Context, not a Starlette Request: a new transport-agnostic Context.headers property (None on stdio).
Exactly-once is per-call resolver memoization (keyed by function identity); cross-call idempotency is intentionally out of scope.
Decline/cancel handling is driven by the consumer's annotation. Annotating the unwrapped model (Annotated[Login, Resolve(login)]) injects the model on accept and aborts the call with an error result on decline/cancel. Annotating the elicitation result union lets the consumer match on accept/decline/cancel instead:

@mcp.tool()
async def whoami(
    login: Annotated[AcceptedElicitation[Login] | DeclinedElicitation | CancelledElicitation, Resolve(login)],
) -> str:
    match login:
        case AcceptedElicitation(data=data):
            return f"hi {data.username}"
        case _:
            return "no username provided"

The resolver dependency graph is analyzed once at registration: unclassifiable resolver parameters and cyclic dependencies raise InvalidSignature there.

Notes

This is purely additive - no breaking changes. New public symbols (Resolve, Elicit, and the re-exported elicitation result types) live in mcp.server.mcpserver, not top-level mcp.
Resolvers and their referenced types must be resolvable by typing.get_type_hints, matching the existing limitation for tool parameter types (locally-scoped types under from __future__ import annotations are not resolvable - this is pre-existing, not introduced here).
Scoped to tools; resources/prompts use a different injection path and can follow.

Tests

tests/server/mcpserver/test_resolve.py (11 tests, 100% coverage of resolve.py): direct value vs Elicit, accept/decline for both unwrapped and union consumers, nested resolvers, exactly-once memoization, by-name tool-arg injection, schema exclusion, sync resolvers, and registration-time cycle/unresolvable-param errors.

AI Disclaimer

This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.

A tool parameter annotated `Annotated[T, Resolve(fn)]` is filled by running the resolver `fn` before the tool body, instead of by the calling LLM. Resolvers form a dependency graph: a resolver may declare its own `Resolve(...)` dependencies, read the `Context` (including the new `Context.headers`), and receive the tool's own arguments by name. A resolver may return `Elicit[T]` to ask the client; the SDK runs the elicitation and injects the answer. Each resolver runs at most once per `tools/call`. The injected type follows the consumer's annotation: the unwrapped model aborts the call on decline/cancel, while the elicitation result union lets the consumer branch on the outcome. Resolved parameters are omitted from the tool's input schema; unclassifiable resolver parameters and cyclic resolver dependencies raise at registration time.

The headers property's request-present branch and the schema-inspection helpers in the resolver tests were not exercised, breaking the 100% coverage gate. Add direct Context.headers tests and mark the never-run helper bodies.

cubic-dev-ai

5 issues found across 8 files

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/migration.md">

<violation number="1" location="docs/migration.md:1408">
P2: Example uses DeclinedElicitation/CancelledElicitation without importing them, so the migration snippet is not runnable.</violation>
</file>

<file name="src/mcp/server/mcpserver/tools/base.py">

<violation number="1" location="src/mcp/server/mcpserver/tools/base.py:83">
P2: Tool registration can leak raw NameError for unresolved type hints. This breaks the existing InvalidSignature error path and returns less actionable failures.</violation>

<violation number="2" location="src/mcp/server/mcpserver/tools/base.py:95">
P2: Resolver by-name classification allows argument names that cannot be injected at runtime. This defers a resolvable-signature error into a runtime failure.</violation>
</file>

<file name="src/mcp/server/mcpserver/resolve.py">

<violation number="1" location="src/mcp/server/mcpserver/resolve.py:97">
P3: `find_resolved_parameters` iterates `hints.items()` which includes `'return'` from `get_type_hints`. Should filter to actual parameters (e.g., using `inspect.signature`).</violation>

<violation number="2" location="src/mcp/server/mcpserver/resolve.py:110">
P1: `_wants_union` misclassifies `AcceptedElicitation[T]` annotations, so tools requesting a specific accepted-result member get unwrapped model data instead of the elicitation result object.</violation>
</file>

_{Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic}

cubic-dev-ai · 2026-06-25T14:44:12Z

+def _wants_union(type_arg: Any) -> bool:
+    """True when `type_arg` is an `ElicitationResult` member (or a union of them)."""
+    members = get_args(type_arg) if get_origin(type_arg) is not None else (type_arg,)
+    return any(isinstance(m, type) and issubclass(m, _ELICITATION_RESULT_MEMBERS) for m in members)


P1: _wants_union misclassifies AcceptedElicitation[T] annotations, so tools requesting a specific accepted-result member get unwrapped model data instead of the elicitation result object.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/mcp/server/mcpserver/resolve.py, line 110: <comment>`_wants_union` misclassifies `AcceptedElicitation[T]` annotations, so tools requesting a specific accepted-result member get unwrapped model data instead of the elicitation result object.</comment> <file context> @@ -0,0 +1,256 @@ +def _wants_union(type_arg: Any) -> bool: + """True when `type_arg` is an `ElicitationResult` member (or a union of them).""" + members = get_args(type_arg) if get_origin(type_arg) is not None else (type_arg,) + return any(isinstance(m, type) and issubclass(m, _ELICITATION_RESULT_MEMBERS) for m in members) + + </file context>

Not a bug. AcceptedElicitation[Login] is a pydantic generic, so subscription produces a real BaseModel subclass (not a typing alias) - get_origin() is None, so _wants_union treats it as a single member and the issubclass(..., AcceptedElicitation) check returns True. Verified end-to-end: Annotated[AcceptedElicitation[Login], Resolve(...)] injects the result object, not unwrapped data. Leaving as-is.

You're right — the parent comment is wrong here. AcceptedElicitation[Login] stays a concrete BaseModel subclass, so _wants_union treats it as a single member and Annotated[AcceptedElicitation[Login], Resolve(...)] injects the result object as intended.

cubic-dev-ai · 2026-06-25T14:44:12Z

        if context_kwarg is None:  # pragma: no branch
            context_kwarg = find_context_parameter(fn)

+        resolved_params = find_resolved_parameters(fn)


P2: Tool registration can leak raw NameError for unresolved type hints. This breaks the existing InvalidSignature error path and returns less actionable failures.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/mcp/server/mcpserver/tools/base.py, line 83: <comment>Tool registration can leak raw NameError for unresolved type hints. This breaks the existing InvalidSignature error path and returns less actionable failures.</comment> <file context> @@ -67,13 +80,23 @@ def from_function( if context_kwarg is None: # pragma: no branch context_kwarg = find_context_parameter(fn) + resolved_params = find_resolved_parameters(fn) + + skip_names = [context_kwarg] if context_kwarg is not None else [] </file context>

Not an issue. find_resolved_parameters resolves hints via _type_hints, which catches the failure and returns {} (no raw NameError). func_metadata is then called and raises a proper InvalidSignature for unresolvable annotations, so the existing error path is preserved. Verified.

The parent comment was wrong here: find_resolved_parameters already swallows unresolved hints and func_metadata still raises InvalidSignature, so there’s no raw NameError leak in this path.

find_resolved_parameters called typing.get_type_hints on the callable directly, which raises for a callable instance (an object with __call__), breaking tool registration for callable objects. Resolve hints off __call__ and tolerate unresolvable hints, mirroring find_context_parameter.

cubic-dev-ai

2 issues found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/mcp/server/mcpserver/tools/base.py">

<violation number="1" location="src/mcp/server/mcpserver/tools/base.py:83">
P2: Tool registration can leak raw NameError for unresolved type hints. This breaks the existing InvalidSignature error path and returns less actionable failures.</violation>
</file>

<file name="src/mcp/server/mcpserver/resolve.py">

<violation number="1" location="src/mcp/server/mcpserver/resolve.py:110">
P1: `_wants_union` misclassifies `AcceptedElicitation[T]` annotations, so tools requesting a specific accepted-result member get unwrapped model data instead of the elicitation result object.</violation>
</file>

_{Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic}

…nging-crown

After merging main, LATEST_PROTOCOL_VERSION is 2026-07-28, which defines no server-to-client requests, so elicitation/create is unavailable at the default negotiated version. Pin these tests to mode='legacy' (negotiates 2025-11-25) where elicitation is supported, matching test_elicitation.py.

…esolver naming - tools/base.py: build tool_arg_names as 'alias or field_name' to match the runtime kwarg keys, so a by-name resolver param on an aliased field resolves instead of raising KeyError at call time. - resolve.py: iterate inspect.signature params (not get_type_hints items, which include 'return') so a Resolve marker on a return annotation is ignored; add _resolver_name so callable-object resolvers raise InvalidSignature instead of AttributeError in error messages. - migration.md: import DeclinedElicitation/CancelledElicitation used in the branching example so the snippet is runnable. Add regression tests for each.

claude

I didn't find any bugs in this implementation, but this PR introduces a new public API surface (Resolve/Elicit dependency injection) and modifies the tool-call execution path, so it warrants a maintainer's review of the design and API choices.

Extended reasoning...

Overview

This PR adds a resolver dependency-injection framework for @mcp.tool() functions: a new ~280-line resolve.py module (resolver detection, DAG analysis with cycle detection, per-call memoized execution, elicitation handling), new public exports from mcp.server.mcpserver (Resolve, Elicit, ElicitationResult and the elicitation result types), a new transport-agnostic Context.headers property, integration into Tool.from_function/Tool.run, and a small refactor of FuncMetadata argument validation. It includes 11 new tests for the resolver module plus two for Context.headers, and a migration-guide section.

Security risks

The feature itself is server-side and additive, but it does introduce two things worth a human's eye: Context.headers exposes raw transport headers to tool/resolver code (the documented pattern derives identity from a header like x-github-user, which is only safe behind a trusted proxy/auth layer), and resolvers bypass the tool's JSON-schema argument validation by design (like Context injection today). Neither is an injection or auth-bypass bug in the SDK, but the API encourages patterns whose security depends on deployment context.

Level of scrutiny

High. This is a new public API with non-trivial design decisions (decline/cancel semantics driven by the consumer's annotation, function-identity memoization, by-name tool-arg injection including alias handling, sync resolvers running in a thread) and it touches the tool-call execution path used by every MCPServer tool. API-surface additions to an SDK are the kind of decision maintainers should explicitly own, regardless of implementation correctness.

Other factors

The implementation is well-tested (the new test_resolve.py covers accept/decline, nesting, memoization, schema exclusion, registration-time errors, aliasing, and callable-object resolvers), and the most recent commits already address the earlier cubic reviewer findings (by-name aliasing, return-annotation handling, callable-resolver naming). My review and the bug-hunting pass found no concrete bugs; the deferral is purely about scope and API design ownership, not correctness concerns.

…nd-method memoization bughunter findings on #2969: - Resolvers may return any type, not just BaseModel. Wrapping the return in AcceptedElicitation(data=...) validated it against the schema bound, so e.g. Annotated[str, Resolve(get_token)] failed every call with a cryptic ValidationError. Use model_construct to wrap the value without validation (the Elicit[T] path still validates via ctx.elicit). - _is_context_annotation now unwraps unions, so a resolver param typed Context | None is accepted, matching find_context_parameter on tools. - Memoize resolvers by the callable itself (hash/eq) instead of id(fn), so a bound-method resolver referenced as auth.login in two places runs at most once and participates in cycle detection. Fresh bound-method objects share identity by (__func__, __self__). Add regression tests for each.

cubic-dev-ai

2 issues found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/mcp/server/mcpserver/tools/base.py">

<violation number="1" location="src/mcp/server/mcpserver/tools/base.py:83">
P2: Tool registration can leak raw NameError for unresolved type hints. This breaks the existing InvalidSignature error path and returns less actionable failures.</violation>
</file>

<file name="src/mcp/server/mcpserver/resolve.py">

<violation number="1" location="src/mcp/server/mcpserver/resolve.py:110">
P1: `_wants_union` misclassifies `AcceptedElicitation[T]` annotations, so tools requesting a specific accepted-result member get unwrapped model data instead of the elicitation result object.</violation>

<violation number="2" location="src/mcp/server/mcpserver/resolve.py:210">
P2: Context detection is over-broad: any generic containing `Context` is treated as a context parameter, not just union/optional context annotations.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic}

cubic-dev-ai · 2026-06-25T16:21:42Z

+    candidates = get_args(annotation) if get_origin(annotation) is not None else (annotation,)
+    return any(isinstance(c, type) and issubclass(c, Context) for c in candidates)


P2: Context detection is over-broad: any generic containing Context is treated as a context parameter, not just union/optional context annotations.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/mcp/server/mcpserver/resolve.py, line 210: <comment>Context detection is over-broad: any generic containing `Context` is treated as a context parameter, not just union/optional context annotations.</comment> <file context> @@ -193,12 +207,13 @@ def _resolve_marker(annotation: Any) -> tuple[Resolve | None, bool]: if get_origin(annotation) is Annotated: annotation = get_args(annotation)[0] - return isinstance(annotation, type) and issubclass(annotation, Context) + candidates = get_args(annotation) if get_origin(annotation) is not None else (annotation,) + return any(isinstance(c, type) and issubclass(c, Context) for c in candidates) </file context>

Suggested change

candidates = get_args(annotation) if get_origin(annotation) is not None else (annotation,)

return any(isinstance(c, type) and issubclass(c, Context) for c in candidates)

origin = get_origin(annotation)

is_union = origin is typing.Union or (

origin is not None and origin.__module__ == "types" and origin.__name__ == "UnionType"

)

candidates = get_args(annotation) if is_union else (annotation,)

return any(isinstance(c, type) and issubclass(c, Context) for c in candidates)

Intentional - this mirrors find_context_parameter exactly, which also matches any generic containing Context (e.g. it returns a param for list[Context] too). Restricting resolvers to unions-only would re-introduce the tool/resolver asymmetry that the earlier review asked me to fix. If the broad match is wrong it should be fixed in both places at once; keeping them in sync here.

The parent comment was too broad here: this resolver check intentionally mirrors find_context_parameter, so narrowing it to unions-only would reintroduce the tool/resolver asymmetry. If the broad match is wrong, both paths should be changed together.

Kludex · 2026-06-25T16:24:17Z

Addressed the three bughunter findings in aac86dc:

Non-BaseModel resolver returns — wrapping the return in AcceptedElicitation(data=...) validated it against the BaseModel bound, so Annotated[str, Resolve(get_token)] failed every call. Now wrapped with model_construct (no validation); the Elicit[T] path still validates via ctx.elicit.
Context | None on resolvers — _is_context_annotation now unwraps unions, matching find_context_parameter on tools.
Bound-method memoization — resolvers are keyed by the callable (hash/eq by (__func__, __self__)) instead of id(fn), so auth.login referenced twice runs at most once and participates in cycle detection.

Each has a regression test. 100% coverage, CI green.

Review follow-ups on #2969: - Tool.run validated arguments twice when resolvers were present (once to feed resolvers, once in call_fn_with_arg_validation). A field with default_factory or a stateful validator could hand a by-name resolver a different value than the tool body. Validate once and pass it through via a new pre_validated argument so both observe the same value. - Key the resolver cache/plans by (id(__func__), id(__self__)) for bound methods and id(fn) otherwise, instead of the callable's equality, so two distinct callables that compare equal can no longer share a plan/cache entry while bound-method memoization still works. Add regression tests.

cubic-dev-ai

2 issues found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/mcp/server/mcpserver/tools/base.py">

<violation number="1" location="src/mcp/server/mcpserver/tools/base.py:83">
P2: Tool registration can leak raw NameError for unresolved type hints. This breaks the existing InvalidSignature error path and returns less actionable failures.</violation>
</file>

<file name="src/mcp/server/mcpserver/resolve.py">

<violation number="1" location="src/mcp/server/mcpserver/resolve.py:110">
P1: `_wants_union` misclassifies `AcceptedElicitation[T]` annotations, so tools requesting a specific accepted-result member get unwrapped model data instead of the elicitation result object.</violation>

<violation number="2" location="src/mcp/server/mcpserver/resolve.py:144">
P2: Fallback keying by `id(fn)` breaks memoization for bound built-in methods, causing duplicate resolver execution when the same method is referenced multiple times.</violation>

<violation number="3" location="src/mcp/server/mcpserver/resolve.py:210">
P2: Context detection is over-broad: any generic containing `Context` is treated as a context parameter, not just union/optional context annotations.</violation>
</file>

<file name="src/mcp/server/mcpserver/utilities/func_metadata.py">

<violation number="1" location="src/mcp/server/mcpserver/utilities/func_metadata.py:95">
P2: `pre_validated` is used by reference and then mutated in place, so caller-provided validated args can be unexpectedly modified across calls.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic}

claude

The earlier double-validation concern is resolved in 37c038c (single validation pass threaded through as pre_validated, with a regression test) and I found no new issues — but this introduces a new public DI API (Resolve/Elicit), new resolver-graph machinery, and changes to the tool call path, so it warrants a maintainer's review of the API design rather than auto-approval.

Extended reasoning...

Overview

This PR adds resolver dependency injection for MCPServer tools: a new ~290-line resolve.py module (Resolve/Elicit markers, resolver DAG analysis, per-call memoized resolution, elicitation integration), new public exports from mcp.server.mcpserver, a transport-agnostic Context.headers property, changes to Tool.from_function/Tool.run, a new validate_arguments/pre_validated seam in func_metadata, plus extensive tests (19 in test_resolve.py) and migration docs.

Security risks

Resolvers run server-defined callables only — the calling client cannot inject or select resolvers, and resolved parameters are stripped from the input schema so clients cannot supply them. Context.headers exposes request headers to tool/resolver code, which is intentional and transport-scoped (None on stdio); no auth or crypto code is touched. The AcceptedElicitation.model_construct path skips validation by design for non-elicited resolver returns, which is internal data, not client-supplied. I see no concrete injection or bypass risk, but the elicitation-driven flow does change how user-confirmation steps are wired, which deserves a human eye.

Level of scrutiny

High. This is a feature-level addition with new public API surface and design decisions (annotation-driven unwrap-vs-union semantics, resolver identity/memoization keys, by-name argument injection, registration-time cycle detection) that a maintainer should deliberately sign off on — it is not a mechanical or pattern-following change. It also modifies the hot path of every tool call (Tool.run, call_fn_with_arg_validation), even though the non-resolver path is behaviorally unchanged.

Other factors

The author has been responsive: all cubic findings were either fixed (with regression tests) or rebutted with verification, and my prior inline finding about double argument validation was fixed in 37c038c by threading a single validated pass through pre_validated — I checked the current code and the fix looks correct. Test coverage of the new module is thorough (accept/decline/cancel, nesting, memoization, aliasing, sync resolvers, registration-time errors). The remaining considerations are design-level (public API shape, scoping to tools only, default-mode interaction with the 2026-07-28 elicitation changes), which is exactly what human review is for.

Review follow-ups on #2969: - _resolver_key now keys any bound method (pure-python or built-in) by its underlying function/name plus __self__ identity, so a built-in bound method (no __func__, fresh object each access) referenced twice still memoizes to one call. - call_fn_with_arg_validation copies the validated args before merging the injected kwargs, so a caller-provided pre_validated dict is never mutated. Add regression tests.

claude · 2026-06-25T17:13:51Z

+Whether the consumer receives the unwrapped model or the full
+`ElicitationResult` union is decided by the consumer's annotation:
+
+- `Annotated[T, Resolve(fn)]` -> unwrapped `T`; decline/cancel aborts the call.
+- `Annotated[ElicitationResult[T], Resolve(fn)]` (or a specific member) -> the
+  full outcome; the consumer branches on accept/decline/cancel.
+
+Each resolver runs at most once per `tools/call` (memoized by function identity).
+"""


🟡 The module docstring (and find_resolved_parameters's docstring) documents Annotated[ElicitationResult[T], Resolve(fn)] as the way for a consumer to receive the full elicitation outcome, but ElicitationResult is a PEP 604 union and is not subscriptable — ElicitationResult[Login] raises TypeError: ... is not a generic class. Either fix the docstrings to show the explicit member union (as migration.md and the tests do), or make ElicitationResult a subscriptable alias (e.g. a TypeAliasType) before re-exporting it from mcp.server.mcpserver.

Extended reasoning...

What the bug is

The new resolve.py module docstring (lines 13–15) and the find_resolved_parameters docstring document the consumer-facing spelling for receiving the full elicitation outcome as:

Annotated[ElicitationResult[T], Resolve(fn)] # "(or a specific member)"

and this PR also newly re-exports ElicitationResult from mcp.server.mcpserver, encouraging exactly that usage. However, ElicitationResult is defined in src/mcp/server/elicitation.py:39 as the PEP 604 union AcceptedElicitation[ElicitSchemaModelT] | DeclinedElicitation | CancelledElicitation. At runtime that is a types.UnionType, which carries no type parameters and is not subscriptable.

Step-by-step proof

from mcp.server.mcpserver import ElicitationResult — works (newly exported by this PR).

Define class Login(BaseModel): username: str.

Evaluate ElicitationResult[Login] → TypeError: AcceptedElicitation | DeclinedElicitation | CancelledElicitation is not a generic class (reproduced on Python 3.11 with pydantic 2.12 in this repo's environment). Pydantic's AcceptedElicitation[T] subscription produces a concrete BaseModel subclass, so the resulting | union is an ordinary, non-generic union type.

How it manifests for users

Without from __future__ import annotations: the user's tool/resolver definition raises TypeError immediately at module import, at the annotation site.

With from __future__ import annotations: the annotation is deferred; when find_resolved_parameters later resolves hints, _type_hints swallows the failure and returns {}, so the Resolve marker is silently dropped and the parameter stays in the LLM-facing input schema — a confusing, silent misbehavior. (Type checkers accept the alias subscription, which makes the runtime failure extra surprising.)

Why nothing in the PR prevents it

The runtime machinery itself (_wants_union) is fine — it correctly handles the explicit member union AcceptedElicitation[Login] | DeclinedElicitation | CancelledElicitation, which is what docs/migration.md, the PR description, and all tests in test_resolve.py actually use. Only the in-code docstrings advertise the broken ElicitationResult[T] spelling, and the new public re-export of ElicitationResult reinforces it.

Impact and fix

This is a documentation/API-surface defect, not a runtime correctness bug in the implemented happy path, so it should not block the PR. The fix is small: either update the two docstrings to show the explicit union (and reconsider whether ElicitationResult belongs in the consumer-facing exports), or make ElicitationResult genuinely subscriptable — e.g. a typing_extensions.TypeAliasType with a type parameter — so the documented spelling actually works and stays consistent with what type checkers already accept.

Kludex added 2 commits June 25, 2026 15:44

Cover Context.headers and resolver schema-only paths

e110093

The headers property's request-present branch and the schema-inspection helpers in the resolver tests were not exercised, breaking the 100% coverage gate. Add direct Context.headers tests and mark the never-run helper bodies.

cubic-dev-ai Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread src/mcp/server/mcpserver/resolve.py

Comment thread src/mcp/server/mcpserver/resolve.py

Kludex added 3 commits June 25, 2026 17:20

Merge remote-tracking branch 'origin/main' into worktree-synthetic-si…

3f59ea3

…nging-crown

claude Bot reviewed Jun 25, 2026

View reviewed changes

cubic-dev-ai Bot reviewed Jun 25, 2026

View reviewed changes

claude Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread src/mcp/server/mcpserver/tools/base.py

cubic-dev-ai Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread src/mcp/server/mcpserver/resolve.py

Comment thread src/mcp/server/mcpserver/utilities/func_metadata.py

claude Bot reviewed Jun 25, 2026

View reviewed changes

		candidates = get_args(annotation) if get_origin(annotation) is not None else (annotation,)
		return any(isinstance(c, type) and issubclass(c, Context) for c in candidates)

-    candidates = get_args(annotation) if get_origin(annotation) is not None else (annotation,)
-    return any(isinstance(c, type) and issubclass(c, Context) for c in candidates)
+    origin = get_origin(annotation)
+    is_union = origin is typing.Union or (
+        origin is not None and origin.__module__ == "types" and origin.__name__ == "UnionType"
+    )
+    candidates = get_args(annotation) if is_union else (annotation,)
+    return any(isinstance(c, type) and issubclass(c, Context) for c in candidates)

Uh oh!

Conversation

Kludex commented Jun 25, 2026

Summary

Design

Notes

Tests

AI Disclaimer

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kludex Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kludex Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Overview

Security risks

Level of scrutiny

Other factors

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kludex Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Kludex commented Jun 25, 2026

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Overview

Security risks

Level of scrutiny

Other factors

Uh oh!

claude Bot Jun 25, 2026

cubic-dev-ai Bot Jun 25, 2026 •

edited

Loading

cubic-dev-ai Bot Jun 25, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot Jun 25, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading