fix(mcpserver): paginate completion values exceeding 100 items (#3649)

[musi22]

Motivation

Fixes #3649

An @mcp.completion() handler returning more than 100 values currently behaves inconsistently across protocol versions:

• On 2026-07-28 sessions: the wire model enforces values: Annotated[list[str], Field(max_length=100)]. Returning >100 values raises a Pydantic ValidationError in runner.py, turning the response into an unhandled -32603 "Handler returned an invalid result" internal error.
• On 2025-11-25 sessions: all values are sent without pagination, violating the MCP specification ("Must not exceed 100 items") while leaving total and has_more unset.

This behavior mirrors the TypeScript SDK's McpServer.createCompletionResult reference implementation:
values: suggestions.slice(0, 100), total: suggestions.length, hasMore: suggestions.length > 100.

Changes

1. src/mcp/server/mcpserver/server.py:

   • In the MCPServer.completion wrapper handler, when len(result.values) > 100:
     • Slice values to the first 100 items (result.values[:100]).
     • Set total = len(result.values) if result.total was not explicitly provided by the handler.
     • Set has_more = True if result.has_more was not explicitly provided.
   • Handlers returning $\le 100$ values or specifying explicit total/has_more values are preserved unchanged.
   • Low-level Server handlers remain untouched.

2. tests/server/mcpserver/test_server.py:

   • Added test_completion_handler_more_than_100_values_paginates verifying pagination across both mode="auto" (2026-07-28) and mode="legacy" (2025-11-25) clients.
   • Added test_completion_handler_more_than_100_values_preserves_explicit_total_and_has_more verifying that explicitly provided metadata takes precedence.

Verification

• Tested with uv run pytest tests/server/mcpserver/test_server.py (all completion tests passing).
• Ran full tests/server/mcpserver/ suite (643 passed, 1 skipped, 0 failures).
• Clean ruff check and ruff format.

[github-actions]

This PR has been closed automatically. It's still a draft, but we close those early so you don't put in more time only to have it closed the moment you mark it ready.

This repo only keeps pull requests open when they come from a maintainer, or from a contributor a maintainer has assigned to the linked issue, and you aren't currently assigned to #3649.

If a maintainer assigns you to #3649, this PR reopens on its own and there's nothing more you need to do here. Assignment is a maintainer call based on capacity; comments that only ask to be assigned don't factor in. What does help is engaging on the issue itself by confirming the repro, explaining why it matters for your use case, or describing the approach you'd take.

You're welcome to keep pushing commits here (just avoid force-pushing, since GitHub can't reopen a rewritten branch), but that on its own won't get the PR reviewed or the issue assigned, and realistically most auto-closed PRs stay closed. There's no need to open a new PR either way.

CONTRIBUTING.md has the full reasoning, but in short:

• We're a small team with very little capacity to review community PRs right now.
• Many recent PRs are AI-generated with little human review, and reviewing one carefully still costs a maintainer as much time as it ever did. A well-described issue is usually more useful to us than the code.

Maintainers: reopen, remove missing-issue-link, or add bypass-issue-check to override.