feat(mcp): migrate to python-sdk v2 (protocol 2026-07-28)

[cbcoutinho]

Migrates to mcp python-sdk 2.1.1 (protocol 2026-07-28), from 1.29.

Closes the work planned on Deck card 946 (board 46, "MCP 2026-07-28 Spec
Adoption"), which blocks every other card on that board.

Deviation from the card's plan — read this first

The card plans 4 stacked PRs (spike / prep-on-v1 / mechanical bump /
semantics). This is one PR. Phase 1 ("prep on v1") is no longer reachable:
the get_context() replacement needs ServerRequestContext, which does not
exist in 1.x, so there is nothing forward-compatible left to land first. And
splitting the bump from the semantics would make the bottom PR knowingly
broken — without the ToolError conversions, tools silently stop explaining
themselves to the model.

Happy to restructure into a stack if you'd rather review it that way; say so and
I'll split it. The semantic changes are the four bullets under Behavioural
below, each with a comment at the site.

Mechanical (the bulk of the diff)

Change	Sites
FastMCP → MCPServer, mcp.server.fastmcp* → mcp.server.mcpserver*	34
McpError(ErrorData(...)) → MCPError(code, message)	141
.isError → .is_error, .structuredContent, .uriTemplate, .inputSchema	~310
ToolAnnotations(readOnlyHint=…) → read_only_hint=	~380
streamablehttp_client → streamable_http_client + httpx2.AsyncClient	3 files
RequestContext → ServerRequestContext / ClientRequestContext	2 files

The ToolAnnotations kwargs were not required — camelCase still constructs,
verified at runtime — but renaming them clears ~200 ty warnings, so ty is
usable again. NextcloudFastMCP → NextcloudMCPServer, since it was named
after a class that no longer exists.

Behavioural — the actual risk

1. request_ctx and get_context() are both gone. v2 injects Context
into tools and template resources only. That left capability gating in
list_tools() and every static @mcp.resource() (nc://capabilities,
notes://settings, cookbook://version) with no route to a context — and
because both callers fail open by design, this would have silently disabled
capability gating rather than crashing. New nextcloud_mcp_server/request_context.py
republishes the context from a middleware, which is where v2 puts per-message
interception.

2. Server.request_handlers is gone — the tool-outcome metrics and
client-fleet instrumentation were patching that dict. Both are now a middleware;
instrument_call_tool_outcomes(mcp) keeps its signature.

3. MCPError from a tool is now a JSON-RPC error, not is_error=True.
The client raises it, so the model never sees the message. All ~140 of our
raise sites are "Note 5 not found" / "Nextcloud access not provisioned" —
failures the model should read and react to, which is precisely what ToolError
means in v2. Mapped back at the call_tool boundary rather than changing the
wire contract for 140 messages.

4. UnexpectedToolError withholds the original message entirely (Error executing tool <name>, nothing more). 21 raise ValueError sites in tool bodies
— "calendar_name is required when search_all_calendars is False", comment
length limits — were reaching the model as text in 1.x and would now reach it as
nothing. Converted to ToolError. A live integration test caught this one.

Also: Streamable HTTP now caps POST bodies at 4 MiB, answering 413 before
parsing, while WEBDAV_WRITE_MAX_MB defaults to 50 MB — max_request_body_size
is now derived from that same setting so the size refusal stays where it can
explain itself. transport_security moved off the constructor onto
streamable_http_app() (see the note appended to
docs/MCP-1.23-DNS-REBINDING-FIX.md). ctx.elicit() raises
NoBackChannelError at 2026-07-28, so the fallback gained a dedicated branch
and a mcp_elicitation_total{reason="no_back_channel"} label. Deck resource
deprecation notices moved out of ctx.warning() — dropped on 2026-era
connections per SEP-2577 — into descriptions clients actually see.

Test coverage

New:

• tests/unit/test_request_context_bridge.py — the middleware bridge, driven
  through a real Client(server) (which negotiates 2026-07-28). Calling the
  methods directly would pass while the served path silently failed open.
• tests/unit/test_tool_errors_stay_tool_results.py — the card's acceptance
  criterion: a Nextcloud 404 and a raised MCPError both land in
  CallToolResult.is_error with a usable message, asserted from the client side.
• tests/smoke/test_protocol_2026.py — closes a coverage gap this port
  surfaced: every existing fixture drives a hand-rolled ClientSession +
  initialize(), which negotiates a 2025-era version, so nothing exercised
  2026-07-28 over HTTP. Uses Client(url) (mode="auto").

The existing ClientSession fixtures deliberately stay on the legacy path —
that is what real clients still speak, and both eras need to keep working.

No new API surface, so no new contract tests; the existing Pact lanes should be
unaffected and are the check on that.

Verification status — please read

Run locally before I was asked to move validation to CI:

• ✅ ruff, ruff format, ty (201 → 0 diagnostics)
• ✅ pytest -m unit — 3727 passed
• ✅ pytest -m contract — 19 passed
• ✅ pytest -m smoke — passed against a live stack over real Streamable HTTP
• ✅ nc://capabilities static resource confirmed working live in single-user
  BasicAuth — the piece with no route to a Context under v2

Not yet run anywhere: -m "integration and not oauth" got to ~78% with all
failures traced to profiles I hadn't started (ports 8003/8004, keycloak, ldap)
rather than regressions — but I did not finish confirming that, so treat it as
unverified. -m oauth, -m ldap, -m login_flow_ldap, -m keycloak have not
run at all. The three new test files above have never been executed — CI is
their first run.

Auth is the surface I'd least want to take on faith here: elicitation losing its
back-channel, and AuthenticatedUser / auth_context_var still being
SDK-internal (unchanged in v2, but only the OAuth lanes prove it).

The card's open item — now closed

Progressive-consent behaviour under a 2026-07-28 client is documented and
deliberate — verify the degradation empirically, don't assume it.

tests/unit/test_elicitation_no_back_channel.py does this, and passes in CI. It
drives the real present_login_url path behind a Client(server) connection
that negotiates 2026-07-28, and asserts the metric reason is specifically
no_back_channel rather than merely that some fallback fired — reason="error"
would mean we were guessing at the cause. It also pins that registering an
elicitation_callback does not rescue it, since that is the obvious wrong fix.

Confirmed, not assumed: the SDK does raise NoBackChannelError, our handler
catches that specific exception, and the tool degrades instead of failing.
Whether losing the clickable prompt is acceptable is a product call — restoring
an interactive one needs the resolver / InputRequiredResult route, which is
Deck card #526.

---

This PR was generated with the help of AI, and reviewed by a Human

🤖 Generated with Claude Code

https://claude.ai/code/session_019iCzZAuCMsZS7UJYfy3htd

[claude]

Claude finished @cbcoutinho's task in 3m 9s —— View job

---

Review: migrate to python-sdk v2 (protocol 2026-07-28)

• Read PR description, comments, and repo CLAUDE.md
• Inspect diff (git diff origin/master...HEAD, 9 commits)
• Review behavioral changes: request-context bridge, MCPError/ToolError boundary, elicitation no-back-channel, derived max request body size
• Review mechanical rename sweep for correctness
• Check test coverage for the new behavior
• Post final review feedback

Summary

This is a large, high-risk migration (mcp 1.29 → 2.1.1, protocol 2026-07-28) handled with unusual care. I read the four behavioral changes in detail plus spot-checked the mechanical rename, and I don't have any blocking findings. The four non-blocking review notes referenced in the PR thread (integration/OAuth/LDAP/Keycloak lanes, SonarCloud complexity, the mcp version range, BaseResponse/capability-gating conformance) all appear to have been addressed already, per the author's 2026-09-04/09-05 comments and the current CI state (Pact lane green; full 27-lane matrix reported green three times on a1b6b225).

What I verified

1. errors.py / the call_tool exception boundary — the three-clause except UnexpectedToolError → except ToolError → except MCPError ordering is correct given UnexpectedToolError subclasses ToolError, and the comment explaining why the order is load-bearing is genuinely useful for the next person touching this. friendly_tool_error falling back to _cause_message when there's no HTTP-specific rendering is a sensible layering.

2. request_context.py / the middleware bridge — republishing ServerRequestContext via a contextvar set in NextcloudMCPServer's middleware, for the three callers (list_tools, static @mcp.resource(), enforce_capability) that the SDK gives no Context to, is the right shape for a stopgap the SDK itself removed. current_context() raising LookupError outside a served request (rather than silently returning something bogus) is the correct failure mode, and test_request_context_bridge.py specifically tests it through a real Client(server) dispatch rather than calling the methods directly — which matters here, since a direct call would pass while silently skipping the middleware.

3. _max_request_body_size() (app.py) — the 4/3 base64-inflation factor plus a flat 1 MiB envelope slack, floored at the SDK's 4 MiB default, is exercised well in test_max_request_body_size.py (default 50 MB case, the 0/None/small-value floor case, and a scaling monotonicity case). I checked the arithmetic against the test's own assertions and it holds.

4. Elicitation NoBackChannelError handling — _run_elicit's catch order (NoBackChannelError before the generic Exception) attributes the fallback to the right metric label, and test_elicitation_no_back_channel.py proves it against a real Client(server) connection negotiating 2026-07-28 rather than a mock — including the "does registering a callback rescue it" negative case, which is exactly the kind of thing someone would try as a wrong fix later.

5. Mechanical sweep completeness — I grepped the full source and test tree for mcp.server.fastmcp/FastMCP, camelCase ToolAnnotations kwargs (readOnlyHint=, etc.), McpError/ErrorData, and .isError — all zero hits outside history. The rename is clean; nothing was missed beyond what the two straggler commits already fixed.

6. sharing.py / test_sharing_link_expiry.py — the RuntimeError/ValueError → ToolError conversions and the corresponding test updates (pytest.raises(ToolError, ...)) are consistent with the boundary change and correctly explained inline.

Non-blocking observations

• The mcp[cli] (>=2.1,<3) range (pyproject.toml) is already flagged in the PR thread as a deliberate, unresolved decision for the repo owner — worth an explicit yes/no before merge given this SDK has now broken assumptions twice, but that's already surfaced and isn't something I'd add to.
• NextcloudMCPServer.__init__ appends _publish_request_context to self.middleware before instrument_call_tool_outcomes(mcp) appends its own middleware in app.py. That ordering happens to be correct (context must be published before anything downstream might want it), but it's an implicit ordering dependency across two files — a one-line comment on instrument_call_tool_outcomes noting it must be registered after the context-publishing middleware (or asserting it defensively) would make that harder to break by accident in a future refactor. Not blocking; today's registration order is correct and tested.

CI status at time of review

The latest push triggered fresh CI (Pact contract tests already green; the full Tests workflow and this review were still queued/in-progress when I looked). Given the author's prior comment that the full 27-lane matrix passed three times on the previous commit (a1b6b225), and this push only added 01fe0bd (a small, self-contained test addition for _max_request_body_size), I'd expect the same result, but I did not wait for it to complete.

Conclusion

No blocking issues found. The behavioral risk surface called out in the PR description is each backed by a targeted test that exercises the real SDK dispatch path rather than mocking around it, which is the right way to de-risk an SDK major-version migration like this.

[cbcoutinho]

Status update — the "never executed" caveat above is now stale

When this PR was opened, three new test files had never run anywhere. They have
now run in CI, and one of them found a real bug in itself:

• ✅ tests/unit/test_request_context_bridge.py
• ✅ tests/unit/test_tool_errors_stay_tool_results.py
• ✅ tests/unit/test_elicitation_no_back_channel.py — failed first, fixed in
  3308a49. Its tool declared ctx with no type annotation, so the SDK treated
  it as a required tool argument instead of injecting it
  (ctx Field required [type=missing]). Nothing else in the unit suite was
  affected.
• tests/smoke/test_protocol_2026.py runs in the integration lanes, still going.

The card's last open item is now closed for real

Progressive-consent behaviour under a 2026-07-28 client is documented and
deliberate — verify the degradation empirically, don't assume it.

test_elicitation_no_back_channel.py now passes in CI, and it asserts the metric
label is specifically reason="no_back_channel" rather than merely that some
fallback happened. That distinction is the whole point: reason="error" would
mean we were guessing at the cause. So this is now confirmed on a real
2026-07-28 connection — the SDK does raise NoBackChannelError, our handler
catches that specific exception, and the tool degrades instead of failing.

It also pins that setting an elicitation_callback does not rescue it, since
that is the obvious wrong fix.

I also rewrote one assertion in that file that was vacuous: it checked that a
login URL appeared in the tool result, but the test's own tool had put it there.
Getting the URL in front of the user is the caller's contract —
server/auth_tools.py builds the URL-bearing message on every non-accepted
branch — not something this helper guarantees, so the test now scopes itself to
the degradation and says so.

SonarCloud

Gate OK on all five conditions (new maintainability rating A). It reports 5
CRITICAL python:S3776 cognitive-complexity findings on
configure_{notes,deck,cookbook,mail,semantic}_tools — these are pre-existing:
those are 400-line registration functions on master too, and the rename sweep
touched lines inside them, which re-attributes them as new code. Not refactoring
them here; five functions at complexity 45–153 is a large unrelated change that
would bury a 106-file migration. Happy to open a follow-up card if you want them
split up.

CI so far

Pass: linting, SonarCloud, unit-test, both Pact lanes, package-smoke
(ubuntu + windows). The 18 integration lanes are re-running after the fixup
push — on the previous run keycloak/nc32, keycloak/nc33, ldap/nc32,
ldap/nc34 and docling had all passed, which covers the OAuth/external-IdP and
the GH #980 DAV-principal regression guards.

[cbcoutinho]

Answering the four non-blocking notes — no code changes needed for any of them, so this PR stays at a1b6b225.

1. Integration/OAuth/LDAP/Keycloak lanes — now green, all of them. This was the right thing to hold on; it was the surface I flagged as least verified. Final state on a1b6b225: 27 SUCCESS, 1 skipped (can-i-deploy, shadow mode per ADR-029), MERGEABLE / CLEAN. That includes all six deployment lanes × nc32/33/34 — single-user, multi-user-basic, login-flow, login-flow-ldap, ldap, keycloak — plus both Pact lanes and package-smoke on ubuntu + windows.

Worth recording that holding on those lanes found a real regression: login-flow ×3 and single-user ×2 failed with a contentless Error executing tool <name>. Two were scope denials — the model was told a call was refused but not that it needed notes.write. Root cause was wider than the raise ValueError sweep in the original commit: ScopeAuthorizationError subclasses Exception (it is also raised on HTTP routes, where ToolError would be the wrong type), and client/talk.py raises plain ValueError. Fixed once at the call_tool boundary in 95cface rather than by converting exception types, since that list is open-ended.

2. SonarCloud complexity — addressed, not deferred. #1437 is stacked on this PR and clears all five: SonarCloud now reports "No issues found", with new_duplicated_lines_density improving 0.8% → 0.6%. Four of the five were measuring the registration idiom rather than the code (no individual tool in notes/deck/mail exceeds McCabe 8); semantic.py needed real decomposition of an 850-line function. Tracked on Deck card 1203.

3. mcp[cli] (>=2.1,<3) — flagged for an explicit owner decision, deliberately not resolved by me. You are right that it deserves a conscious "yes" rather than a default, and that is the repo owner's call, not mine. The argument for the range as-is: uv.lock pins 2.1.1, so reproducibility is unaffected today and nothing moves without a deliberate uv lock --upgrade; the range matches how Renovate manages this repo's other deps. The argument against, which I think is the stronger one and which I raised before you did: this SDK has now broken this project's assumptions twice (1.23's DNS-rebinding auto-enable, and this entire migration), so 2.2 arriving unremarked is a real risk. I have left it open in the PR body rather than narrowing it unilaterally.

4. Agreed — no BaseResponse, capability-gating or _make_request violations; that part of the diff is pure identifier renaming.

One correction to the review, since it affects how much weight note 1 carries: the summary says several lanes "hadn't run at PR-open time" and cites a prior partial run. That was accurate when written. As of a1b6b225 the full matrix has completed green three times, and the two intermediate red rounds were the exception-message regression above plus a stale pytest.raises(RuntimeError) assertion in tests/unit/server/test_sharing_link_expiry.py that I missed when changing _build_link_response.

ruff, ruff format and ty clean (ty: 201 → 0 diagnostics). Unit, smoke and both contract tiers green in CI.

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.7% Duplication on New Code

See analysis details on SonarQube Cloud