Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

MCPServer completion handler returning more than 100 values fails on 2026-07-28 sessions and violates the 100-item limit on 2025-11-25 sessions

Aberta Para iniciantes
  • Algo errado?
#3,649 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
2/5
Tempo estimado
1-3 horas
Facilidade para iniciantes
88/100
Tipo de issue
Bug
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
python
Domínio
backend-api-design

Direção de pesquisa

Comece pelo wrapper MCPServer.completion em mcp/server/mcpserver.py (linhas ~759-766), que repassa o Completion do handler sem alterações; o limite de 100 itens fica em mcp_types/_v2026_07_28 e é aplicado em runner.py:381, então o wrapper deve truncar para 100 valores e definir total/has_more antes da validação, preservando os valores definidos pelo handler. Compare com createCompletionResult do SDK TypeScript. Pronto significa um teste de regressão em tests/server/mcpserver/ usando um Client em memória que passe para mode="auto" (2026-07-28) e mode="legacy" (2025-11-25), retornando 100 valores com has_more=True.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

spec-2026-07-28 v2
Initial Checks
Release line

2.x (current stable)

Description

An @mcp.completion() handler that returns more than 100 values behaves differently depending on the negotiated protocol version, and both behaviours are wrong:

  • 2026-07-28 session: the whole completion/complete request fails with -32603 "Handler returned an invalid result". The user gets no suggestions at all.
  • 2025-11-25 session: all values go out on the wire. The spec says values "Must not exceed 100 items", and total / hasMore are left unset, so the client can't tell the list was too long.

It's easy to hit with the filter-by-prefix pattern from docs/servers/completions.md. When the user hasn't typed anything yet (argument.value == ""), every candidate matches, so any handler over a list of more than 100 options (countries, time zones, repos, file names, and so on) fails as soon as the field is focused.

The 100-item cap is only enforced by the 2026-07-28 wire model (Completion.values: Annotated[list[str], Field(max_length=100)] in mcp_types/_v2026_07_28). runner.py:381 checks results against that model and turns the ValidationError into a generic INTERNAL_ERROR. The 2025-11-25 wire model has no such constraint, so nothing stops the oversize list there. The MCPServer.completion wrapper (server.py:759-766) passes the handler's Completion through as-is.

For comparison, the TypeScript SDK's McpServer truncates to 100 and fills the pagination hints (createCompletionResult: values.slice(0, 100), total: suggestions.length, hasMore: suggestions.length > 100).

Expected: the same handler works on both protocol versions. The client receives the first 100 values with total / hasMore telling it more exist, as Completion's own docstring ("total … can exceed the number of values actually sent") and the docs' total= / has_more= note describe.

Server log on the 2026-07-28 session:

ERROR    handler for 'completion/complete' returned an invalid result
pydantic_core._pydantic_core.ValidationError: 1 validation error for CompleteResult
completion.values
  List should have at most 100 items after validation, not 150 [type=too_long, ...]

I reported this and would like to fix it. Proposed approach: in the MCPServer.completion wrapper, when the handler returns more than 100 values, send the first 100 and set total (to the full count) and has_more=True. Values the handler set explicitly win. Handlers returning ≤100 values are unchanged. The lowlevel Server stays as it is, since a lowlevel handler builds the CompleteResult itself. I'd add a regression test in tests/server/mcpserver/ using an in-memory Client, covering both mode="auto" (2026-07-28) and mode="legacy" (2025-11-25). It's roughly 10 lines of source. If you'd prefer a different behaviour (for example, raising a clear error at the wrapper instead of truncating), I'm happy to do that.

I used an AI assistant to help narrow this down; I ran the reproduction myself on 2.3.0 and on main.

Example Code
import anyio
from mcp_types import Completion, PromptReference
from mcp.client import Client
from mcp.server.mcpserver import MCPServer

COUNTRIES = [f"country-{i:03}" for i in range(150)]

mcp = MCPServer("demo")


@mcp.prompt()
def travel(country: str) -> str:
    return f"Plan a trip to {country}"


@mcp.completion()
async def complete(ref, argument, context):
    # Filter by the typed prefix, as in docs/servers/completions.md; an empty prefix matches everything.
    return Completion(values=[c for c in COUNTRIES if c.startswith(argument.value)])


async def main() -> None:
    for mode in ("auto", "legacy"):
        async with Client(mcp, mode=mode) as client:
            try:
                result = await client.complete(
                    ref=PromptReference(type="ref/prompt", name="travel"),
                    argument={"name": "country", "value": ""},
                )
                c = result.completion
                print(f"{client.protocol_version}: {len(c.values)} values, total={c.total}, has_more={c.has_more}")
            except Exception as e:
                print(f"{client.protocol_version}: {type(e).__name__}: {e}")


anyio.run(main)

Output:

2026-07-28: MCPError: Handler returned an invalid result
2025-11-25: 150 values, total=None, has_more=None
Python & MCP Python SDK
Python 3.12.12, mcp 2.3.0, pydantic 2.13.5 (PyPI release)
Python 3.14.0, mcp main @ 91941ed, pydantic 2.12.5
Windows 11
Linguagem predominante
Python
Estrelas
24.5k
Forks
4k
Merge médio
1d 13h
PRs com merge (30d)
35

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de modelcontextprotocol/python-sdk

Todas as issues de modelcontextprotocol/python-sdk

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.